Burti Rest API

What is Rest API?

A RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.

A RESTful API - also referred to as RESTful web service - is based on representational state transfer (REST) technology, an architectural style and approach to communications often used in web services development.

REST technology is generally preferred to the more robust Simple Object Access Protocol (SOAP) technology because REST leverages less bandwidth, making it more suitable for internet usage. An API for a website is code that allows two software programs to communicate with each another. The API spells out the proper way for a developer to write a program requesting services from an operating or other application.

A RESTful API breaks down a transaction to create a series of small modules. Each module addresses a particular underlying part of the transaction. This modularity provides developers with a lot of flexibility. 

How to set up Burti Rest API?

It is necessary to create script in server folder run-burti-web-api-requests.sh that will contain requests to the server, using the curl command-line tool:

curl "http://localhost:1402/Web_JSON_Composer.hal" -d @sample.get.data.txt > response.get1.json
curl "http://localhost:1402/Web_JSON_Composer.hal" -d @sample.get.data2.txt > response.get2.json
curl "http://localhost:1402/Web_JSON_UpdatingComposer.hal" -d @sample.post.data.txt > response.post.json

The requests are as follows:

h4. Request full details for a specific Item
sample.get.data.txt - made to the READ interface Web_JSON_Composer.hal:

0_query=Web_JSON_INVc_List.hal&0_full=true&0_index=Code&0_Code=10101&0_company=1&0_fieldcnt=1&0_fieldlist=Code

h5. Parameters explained
As you can see, all the parameters are prefixed with a "0_" - this is a number for the request, and is used to make multiple data requests within a single API call. In this example, there is only one data request.
# query - the specific data interface (will be a separate interface for each register). In this case it's "Web_JSON_INVc_List.hal" for Items (register code INVc) - the naming of this interface will be the same accross all registers.
# full - whether to request the full data or a shorter list of fields - these fields are configured separately
# index - the index in Hansaworld's datadef, by which to lookup the data, advanced topic, simply use "Code" (might be something other for other registers)
# Code - the field name within the index, simply use "Code" (might be something other for other registers)
# fieldcnt - number of fields within the index, use 1 (might be something other for other registers)
# company - the company number from which we are requesting the data
# fieldlist - list of the fields within the index, comma separated, use "Code" (might be something other for other registers)

h4. Request full list of items
sample.get.data2.txt - made to the READ interface Web_JSON_Composer.hal:

0_query=Web_JSON_INVc_List.hal&0_count=500&0_full=false&0_sort_only=true&0_index=Code&0_company=1&1_query=Web_JSON_INVc_List.hal&1_count=500&1_full=false&1_sort_only=true&1_index=Code&1_company=2

h5. Parameters explained
In this example you can see that there are two groups of parameters - prefixed with "0_" and "1_". This illustrates two separate data requests within a single call. The response data will be similarly grouped.

Only describing new options that are not described above:
# sort_only - this will use the provided index name as a sort order only, and will not try to look up specific data (used when listing all records within a register)

h4. Insert a new item
sample.post.data.txt - made to the WRITE interface Web_JSON_UpdatingComposer.hal:

{
"0": {
"name": "WEB_JSON_INVc_Save.hal",
"company": 2,
"data": {
"action": "insert",
"matrix": [],
"Code": "10101",
"Name": "Media keyboard"
}
},
"2": {
"name": "WEB_JSON_INVc_Save.hal",
"company": 2,
"data": {
"action": "insert",
"matrix": [],
"Code": "10102",
"Name": "Media keyboard 2"
}
} 
}

h5. Parameters explained

As you can see, the request is now in JSON format. It is once again numbered and can contain multiple requests within the single call. These would be expected to be numbered 0, 1, 2 and so on.

# {{name}} - the name of the update interface. The principle is similar to the read interfaces.
# {{company}} - the company number to use for inserting data
# {{data}} - the data block
# {{action}} - insert/update/delete
# {{matrix}} - to be used with matrix rows - array of rows in the same format as the following
# {{Code}}, {{Name}} - database fields to update with values