To query the data, there are 4 ways:

  • Get All: get all customers in the database.
  • Get By Code: get a single entity by providing its CODE, like getting the information of a customer whose the CODE is "VLADIMIR".
  • Get By ID: get a single entity by providing its ID (GUID).
  • Get By Criteria: get a list of entities or a projection by giving one or more conditions.

Parameters:

In addition, for each request, we also support some parameters in the URL for the JSON format result: 

maxLevel :  indicate the entity level that will be serialized with the result in JSON format. Like Customer has info of Third and Vat. Third has info of Address and Country...

    

Level 1 : Customer

Level 2 : Vat and Third of Customer

Level 3 : Address and Country. And so on.

The higher the level is, the more information client gets but the less performance of request. The default level of the request is 1 if the URL doesn't specify the level.

isShowID: the communication between client and WINBOOKS REST API, ID can be useless in the case of the database being different, because ID has different values, so we use code instead. But in some specific cases like when object does not have the CODE, the ID is needed. The parameter IsShowID equals TRUE, it means the result also contains the ID from the database. The parameter IsShowID equals FALSE, it means the result does not contain ID. The default value of the IsShowID is TRUE.

All parameters above should be included after symbol '?' of the URL that follows the below example

{ REST API Host }   / app /  { Winbooks OM }   /   { Code }   /   Folder /   { FolderCode }?isShowId=true&maxLevel=3

A. Get All

Query all object rows existing in database.

a.  Using HTTP

URL : { REST API Host } / app / { Winbooks OMS } / Folder / { FolderCode } ? {parameter : optional}
Method : GET
Header :
     Authorization : Bearer {access_token}
     Accept : application/json

The below example will get all the customers of the PARFIWEB_DEMO folder:

URL  https://rapi.winbooksonweb.be/app/Customers/Folder/PARFIWEB_DEMO

Method : GET

Header : 

Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St10nMW8y32Skn1fDtrahrgF04FHvphfTFiNCe036WNjxf9W3At366CP1CBUbavQJ_si4pD2Sv39OVWb3fsbFXuHzexYotYgYIYRER_9cOQsFKNOK5GmFcbG4ENAEAAIAAAAAo4sEGwhHdbCq0IMjbsBb1J5y4k0fK6_gI51WK6sEXsdFHScSghffuTb1k8PSt/....

Accept application/json

b. Using Winbooks.Apis.Services


Get All Customers

// Get All Customer            
EntitiesServices folderRESTAPIDEMO = new EntitiesServices(userCredential, "PARFIWEB_DEMO" );
folderRESTAPIDEMO.GetAll<Customer>();

If everything is valid, a successful response will return with status code 200 and the content of the response is the list of all customers in JSON format. Client could handle JSON string by itself or use WinbooksConverter tool for converting JSON string to Winbooks object.

B. Get By Code

Get single object by providing its code.

a. Using HTTP

URL :  { REST API Host } / app / { Winbooks OM } / { Code } / Folder/ { FolderCode } ? {parameter : optional}
Method : GET
Header :
    Authorization : Bearer {access_token}
    Accept : application/json

The example below will get the CUSTOMER with CODE "VLADIMIR" in folder "PARFIWEB_DEMO"

URL  https://rapi.winbooksonweb.be/app/Customer/VLADIMIR/Folder/PARFIWEB_DEMO

Method : GET

Header : 

Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St10nMW8y32Skn1fDtrahrgF04FHvphfTFiNCe036WNjxf9W3At366CP1CBUbavQJ_si4pD2Sv39OVWb3fsbFXuHzexYotYgYIYRER_9cOQsFKNOK5GmFcbG4ENAEAAIAAAAAo4sEGwhHdbCq0IMjbsBb1J5y4k0fK6_gI51WK6sEXsdFHScSghffuTb1k8PSt/....

Acceptapplication/json

b. Using Winbooks.Apis.Services


Get Customer By Code

// GET CUSTOMER WITH CODE VLADIMIR 
EntitiesServices folderRESTAPIDEMO = new EntitiesServices(userCredential, "PARFIWEB_DEMO" );
folderRESTAPIDEMO.GetByCode<Customer>( "VLADIMIR" );

If everything is valid, a successful response will return with status code 200 and the content of the response is the customer "VLADIMIR" in JSON format. Client could handle JSON string by itself or use WinbooksConverter tool for converting JSON string to Winbooks object

C. Get By ID

a. Using HTTPs

URL :  { REST API Host } / app / { Winbooks OM } / { ID } / Folder/ { FolderCode } ? {parameter : optional}
Method : GET
Header :
    Authorization : Bearer {access_token}
    Accept : application/json

The example below will get the CUSTOMER with ID 79A2E56E-2BE7-4216-BA75-9F9400FB45BD in folder "PARFIWEB_DEMO"

URL  : https://rapi.winbooksonweb.be/app/Customer/79A2E56E-2BE7-4216-BA75-9F9400FB45BD/Folder/PARFIWEB_DEMO

Method : GET

Header : 

Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St10nMW8y32Skn1fDtrahrgF04FHvphfTFiNCe036WNjxf9W3At366CP1CBUbavQJ_si4pD2Sv39OVWb3fsbFXuHzexYotYgYIYRER_9cOQsFKNOK5GmFcbG4ENAEAAIAAAAAo4sEGwhHdbCq0IMjbsBb1J5y4k0fK6_gI51WK6sEXsdFHScSghffuTb1k8PSt/....

Acceptapplication/json

b. Using Winbooks.Apis.Services


Get By ID

//GETTING INFO OF CUSTOMER WHICH HAVE ID
Customer CustomerWithId = folderPARFIWEB.GetById<Customer>( "79A2E56E-2BE7-4216-BA75-9F9400FB45BD" );

D. Get By Criteria

Get a list of objects matching some conditions.

a. Using HTTP

URL : { REST API Host } / app / { Winbooks OMS } / Folder / { FolderCode }/ExecuteCriteria ? {parameter : optional}
Method : POST
Header :
    Authorization :  Bearer { access_token }
    Accept: application/json ( this indicates that client wants the result in json format)
    Content-type: application/json ( this indicates the content body of this request is in json format)
Body content : {criteria in json format }

**To transform criteria in JSON format, we call the method JsonCriteriaSerialize() in WinbooksDAO
Get Criteria in JSON format

//GET ALL THE ACTIVE AND UNLOCK CUSTOMER
ICriteria criteria = new CustomerDAO().CreateCriteria();
criteria.Add(Condition.Eq(Customer.Names.IsLocked, false ));
criteria.Add(Condition.Eq(Customer.Names.IsHidden, false ));
var stringCriteria = criteria.JsonCriteriaSerialize();

The criteria in JSON string will have a format like this:  

{
   "EntityType": "Winbooks.TORM.OM.Customer, Winbooks.TORM.OM",   
   "IsCustomization": false,
   "Alias": "this",
   "Association": {},
   "Conditions": [
      {
         "Operator": 0,
         "PropertyName": "IsLocked",
         "OtherPropertyName": "",
         "Values": [
            false
         ],
         "ValueTypes": [
            "System.Boolean, mscorlib"
         ]
      },
      {
         "Operator": 0,
         "PropertyName": "IsHidden",
"OtherPropertyName": "",
"Values": [ false ],
"ValueTypes": [ "System.Boolean, mscorlib" ]
}
],
"Havings": [],
"ProjectionsList":
[],
"Orders": [],
"Params": {},
"FirstResult": -1,
"MaxResult": -1,
"ResultState": 0
}

The example below will get the CUSTOMERS that are unlocked and active in folder "PARFIWEB_DEMO"

URL https://rapi.winbooksonweb.be/app/Customers/Folder/PARFIWEB_DEMO/ExecuteCriteria

Method  : POST

Header:

Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St ....

Accept application/json

Content application/json

Body content {"EntityType": "Winbooks.TORM.OM.Customer, Winbooks.TORM.OM","Alias":"this","Association":{},"Conditions":[{"Operator":0,"PropertyName":"IsLocked","OtherPropertyName":"","Values":[false]},{"Operator":0,"PropertyName":"IsHidden","OtherPropertyName":"","Values":[false]}],"ProjectionsList":[],"Orders":{},"Params":{},"FirstResult":-1,"MaxResult":-1,"ResultState": 0}

b. Using Winbooks.Apis.Services 


THE ACTIVE AND UNLOCK CUSTOMER WITH PAGINATION BY 5

//GET ALL THE ACTIVE AND UNLOCK CUSTOMER WITH PAGINATION BY 5            
ICriteria criteria = new CustomerDAO().CreateCriteria();
criteria.Add(Condition.Eq(Customer.Names.IsLocked, false ));
criteria.Add(Condition.Eq(Customer.Names.IsHidden, false ));
criteria.SetFirstResult(1);
criteria.SetMaxResults(5);
IList<Customer> customerCollection = folderPARFIWEB.GetFilterAll<Customer>(criteria);

c. Operators in the ExecuteCriteria

public enum Operator : short
{
Eq = 0,
EqProperty = 1,
Between = 2,
Ge = 3,
GeProperty = 4,
Gt = 5,
GtProperty = 6,
In = 7,
IsNotNull = 8,
IsNotEmpty = 9,
IsNull = 10,
IsEmpty = 11,
IsNotNumeric = 12,
IsNumeric = 13,
Le = 14,
LeProperty = 15,
Like = 16,
Lt = 17,
LtProperty = 18,
Or = 19,
And = 20,
Not = 21,
Select = 22,
Distinct = 23,
SelectTop = 24,
Avg = 25,
Count = 26,
First = 27,
Last = 28,
Max = 29,
Min = 30,
Sum = 31,
GroupBy = 32,
Having = 33,
UCase = 34,
LCase = 35,
Mid = 36,
Len = 37,
Round = 38,
Now = 39,
Format = 40,
CaseWhen = 41,
Cast = 42,
Constant = 43,
FromAlias = 44,
RowNumber = 45,
DateAdd = 46,
DateDiff = 47,
All = 48,
RowCount = 49,
Exists = 50,
Concat = 51,
Left = 52,
Right = 53,
Function = 54,
Abs = 55,
SubQuery = 56,
LTrim = 57,
RTrim = 58,
DatePart = 59,
Union = 60,
UnionAll = 61,
Grouping = 62,
Rank = 63,
DenseRank = 64
}

E. Chunking data

In some cases, the result is a big data with thousand objects inside. Process big data in one time will make API server slow down and also hard for client when getting result. So we need chunking data in multipart.

For doing this, we make a communication between client and API server. Everytime, the result is a big data, API will only process 100 object per times and return with extra header ContinuePath. Content of this header will make API know the next time client send request with this header, API will process next 100 of previous result. Keep doing this communication until we have a full result ( finished when client does not receive this header anymore)

Example :

We want getting a list object A with 2 level data inside. And an object A will have structure like this

  •  A[100]
    • B[7]
    • C[7]

 

So for each full object A, server need to process 14 objs inside making a total of 15 objects.

A request in API is limit process 100 objects .

This mean at first request, the response  will have json string of 6 object A with full 2 layer ( 6 *15 = 90 objects) , the 6th (we counting from 0) will only have 10 objects inside ( 1 object A + 7 object B + 2 object C) . The response content header will appear new header "ContinuePath”: “ 6|ListC[1] ”

For continue getting data, we making the second request, the same as the first one . Just add the header we just receive   " ContinuePath ”: “  6|ListC[1] ”

Then the result will be 5 objects remain in first request C2 … C6 of the 6th object A, and then the next 6 full object A from A[7] .. A[12] , the 13th will have 5 obj inside (1 object A + 4 object B). and the continue header will be “ContinuePath” : “13|ListB[3]

So, if the list result is a list 100 obj A in 2 layer, we need to make 15 request for getting whole data

Summary by steps 


Step 1First request for getting data

Request :

URLhttps://beta-rapi.winbooksonweb.be/app/ObjectA/Folder/DEMOWOW?maxLevel=2

Headers

  Authorization : Bearer {access token}

  Accept : application/json

Response :

Response Header :

  ContinuePath: 6|ListC[1]

Response content :


[
   {
      "type": "A",
      "ID": "A0",
      "property1": "propertyValue1",
      "property2": "propertyValue2",
      "ListB": [
         {
            "type": "B",
            "ID": "B0"
         },
         {
            "type": "B",
            "ID": "B1"
         },
         {
            "type": "B",
            "ID": "B2"
         },
         {
            "type": "B",
            "ID": "B3"
         },
         {
            "type": "B",
            "ID": "B4"
         },
         {
            "type": "B",
            "ID": "B5"
         },
         {
            "type": "B",
            "ID": "B6"
         }
      ],
      "ListC": [
         {
            "type": "C",
            "ID": "C0"
         },
         {
            "type": "C",
            "ID": "C1"
         },
         {
            "type": "C",
            "ID": "C2"
         },
         {
            "type": "C",
            "ID": "C3"
         },
         {
            "type": "C",
            "ID": "C4"
         },
         {
            "type": "C",
            "ID": "C5"
         },
         {
            "type": "C",
            "ID": "C6"
         }
      ]
   },
   "...",
   {
      "type": "A",
      "ID": "A6",
      "property1": "propertyValue1",
      "property2": "propertyValue2",
      "ListB": [
         {
            "type": "B",
            "ID": "B0"
         },
         {
            "type": "B",
            "ID": "B1"
         },
         {
            "type": "B",
            "ID": "B2"
         },
         {
            "type": "B",
            "ID": "B3"
         },
         {
            "type": "B",
            "ID": "B4"
         },
         {
            "type": "B",
            "ID": "B5"
         },
         {
            "type": "B",
            "ID": "B6"
         }
      ],
      "ListC": [
         {
            "type": "C",
            "ID": "C0"
         },
         {
            "type": "C",
            "ID": "C1"
         }
      ]
   }
]


Step 2 : Second request 

Request :

URLhttps://beta-rapi.winbooksonweb.be/app/ObjectA/Folder/DEMOWOW?maxLevel=2

Headers

Authorization : Bearer {access token}

Accept : application/json

ContinuePath: 6|ListC[1]

Response

Header:

ContinuePath: 13|ListB[3]

Content

[
   {
      "type": "A",
      "ID": "A6",
      "ListC": [
         {
            "type": "C",
            "ID": "C2"
         },
         {
            "type": "C",
            "ID": "C3"
         },
         {
            "type": "C",
            "ID": "C4"
         },
         {
            "type": "C",
            "ID": "C5"
         },
         {
            "type": "C",
            "ID": "C6"
         }
      ]
   },
   "...",
   {
      "type": "A",
      "ID": "A13",
      "property1": "propertyValue1",
      "property2": "propertyValue2",
      "ListB": [
         {
            "type": "B",
            "ID": "B0"
         },
         {
            "type": "B",
            "ID": "B1"
         },
         {
            "type": "B",
            "ID": "B2"
         },
         {
            "type": "B",
            "ID": "B3"
         }
      ]
   }
]


** As you can see, Id or code will always exist, so we could base on that to merge 2 result in unique json string

…. Keep continue until client no longer receive header ContinuePath

Top

  • No labels