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
2. Insert Data and Update Data
To Insert and Update data we have 2 ways
- Insert or Update Single object
- Insert or Update List Object
* Standard json format: is available for all client, especially client not using our support library like Apis - light and easy to use
**Non-standard json format: is still in json format but have some additional special properties processed by our DAL or OM, this json is usually generated by our lib : Winbooks.Serializer . Suitable for client using our DAL and OM dll to perform complicated task
A. Insert Single Object
This function is used for inserting single data object in API
a. Using HTTP
|
In .NET, for making body content, client could use WinbooksConverter
Serialize by WinbooksConverter
|
And this is the result we'll include in the body content of request ,
non-standard json format
|
or if client not using our serializer , we could make it more simple
standard json
|
**Note : For standard json in single object, json string could contain Id/code of object . If not contains, we will get id/code from url
With multiple objects, each json member in json array must have id/code
If the request is successful, the result will be as below with status code 201.
b. Using Winbooks.Apis.Services
|
B. Insert List of Objects
This function is used to Insert or Update a list of objects.
a. Using HTTP
|
In .NET & C#, client could use WinbooksConverter to create the body content
Convert list of Winbooks objects to JSON
|
If client not using our converter, standard json string will be like this
Standard json with multiple object
|
**Note :With multiple objects, each json member in json array must have id/code
b. Using Winbooks.Apis.Services
Insert list Of Customers
|
C. Update single object
This function is used for updating single data object in API- update has the same structure with insert, just change Http verb "POST" into "PUT"
a. Using HTTP
|
In .NET & C#, client could use WinbooksConverter to create the body content
Update single object
|
And this is the result we'll include in the body content of request
|
If the request is successful, the result will be as below with status code 200
b. Using Winbooks.Apis.Services
|
D. Update List of Objects
This function is used for updating list of objects in API
a. Using HTTP
|
In .NET & C#, client could use WinbooksConverter to create the body content
|
if the request is successful, the result will be as below with status code 200
|
b. Using Winbooks.Apis.Services
|
3. Delete Data
We have 5 ways for deleting data in API :
- Delete by single Code
- Delete By ID
- Delete by List of Code
- Delete By Criteria
- Delete all data objects
A. Delete By Single Code
This function is used to delete a single object by giving its code.
a. Using HTTP
|
If the object is deleted successfully, a response with success status 200 code will be returned
The example below will delete a customer with code " VLADIMIR " in folder " PARFIWEB_DEMO "
URL: https://rapi.winbooksonweb.be/app/Customer/VLADIMIR/Folder/PARFIWEB_DEMO
Method : DELETE
Header :
Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St ....
b. Using Winbooks.Apis.Services
Delete Customer By Code
|
B. Delete By ID
a. Using HTTP
The same as Delete By Single Code, just replay Code by ID
b. Using Winbooks.Apis.Services
Delete by Id
|
C. Delete By List of Codes
This function is used to delete a list of objects by giving a list of codes.
a. Using HTTP
|
If the object is deleted successfully, a response with success status 200 code will be returned and contains the list of objects deleted successfully and failed
The example below will delete a list of customer with code "VLADIMIR,TITAN,JIMMY,JORDAN,SPARKLES" in folder "PARFIWEB_DEMO"
URL : https://rapi.winbooksonweb.be/app/Customers/Folder/PARFIWEB_DEMO?code=VLADIMIR,TITAN,JIMMY,JORDAN,SPARKLES
Method : DELETE
Header :
Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St ....
b. Using Winbooks.Apis.Services
|
D. Delete By Criteria
This function is used to delete a list of objects by giving a condition.
a. Using HTTP
|
** for getting criteria in json format, please take a look at function "Get By Criteria"
The example below will delete all Customers whose country code is "GB "
URL : https://rapi.winbooksonweb.be/app/Customers/Folder/PARFIWEB_DEMO/DeleteByCriteria
Method : POST
Header :
Authorization : Bearer gAAAAEg9vKjrggECqOrp6bekZ0KO6_86-URgC5D1xYxXqexQyaOu_St ....
Content : application/json
Accept : application/json
Body content : {"Alias":"this","Association":{"t":{"OwnerAlias":null,"AliasName":"t","Type":"Winbooks.TORM.OM.Third, Winbooks.TORM.OM, Version=1.66.3.0, Culture=neutral, PublicKeyToken=null","JoinType":1,"Properties": ["Id","Third_Id"],"Condition":null},"c":{"OwnerAlias":null,"AliasName":"c","Type":"Winbooks.TORM.OM.Country, Winbooks.TORM.OM, Version=1.66.3.0, Culture=neutral, PublicKeyToken=null","JoinType":1,"Properties": ["Id","t.VatCountry_Id"],"Condition":null}},"Conditions":[{"Operator":0,"PropertyName":"c.Code","OtherPropertyName":"","Values":["GB"]}],"ProjectionsList":[],"Orders":{},"Params":{},"FirstResult":-1,"MaxResult":-1}
b. Using Winbooks.Apis.Services
Delete By Criteria
|
E. Delete All Data Objects
This function is used to clear all data objects.
a. Using HTTP
|
b. Using Winbooks.Apis.Service
Delete All Customer
|