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 us "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
|
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
|
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
|
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/....
Accept: application/json
b. Using Winbooks.Apis.Services
Get Customer By Code
|
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
**The same as getting by code, just replace {Code} by ID value
b. Using Winbooks.Apis.Services
Get By ID
|
D. Get By Criteria
Get a list of objects matching some conditions.
a. Using HTTP
|
**To transform criteria in JSON format, we call the method JsonCriteriaSerialize() in WinbooksDAO
Get Criteria in JSON format
|
The criteria in JSON string will have a format like this:
|
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 : {"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}
b. Using Winbooks.Apis.Services
THE ACTIVE AND UNLOCK CUSTOMER WITH PAGINATION BY 5
|
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
So for each full object A, server need to process 15 objs inside. 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 1: First request for getting data
Request :
URL: https://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 :
URL: https://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