REST & Open as App - A perfect match
As introduced in our blog article, Open as App supports REST based apps now, which opens a whole new world of possibilities and ideas for apps. In the following article we want to give you a more technical insight into the implementation and requirements that your REST API needs to fulfill to be compatible with Open as App. Good news is, we implemented default REST behavior and rules, which makes it easy for you to start.
To make it as easy as possible Open as App follows standard REST conventions
For this article we will be using https://restcountries.eu/rest/v2/all as an example for a REST interface. The API returns a list of countries including name, further details and a link to the respective flag image.
Reading a REST service
All of the data received from REST services that should be connected has to be in JSON format. In our example the simplified response to a GET request to https://restcountries.eu/rest/v2/all looks like this.
[
{
"name":"Afghanistan",
"alpha2Code":"AF",
"alpha3Code":"AFG",
"capital":"Kabul",
"region":"Asia",
"subregion":"Southern Asia",
"population":27657145
}
]
Data has to be transferred using JSON format
Second, it is important that the REST response works with flat data, that means nested responses are not allowed, but all content is put in the top-level of the JSON response. As you can see above the response to the GET call that is used for reading data starts with an ‘[‘ which indicates a list and delivers the first result record directly afterwards. (Indicated by the ‘{‘)
The JSON has to return flat data - no nested structures before the result!
Writing back to a REST service
Besides reading a REST interface Open as App also supports writing back to the respective APIs. This is done by a PATCH request that includes the changed fields in the body, again encoded with JSON.
The request only contains changed fields and needs to have the respective ID column of the data record included. To support writing back to your REST data source, the only thing you have to do is defining the ID column on the list element using idcolumn=index1(,index2) in the Open as App configuration.
After defining an ID column on your lists, write requests (HTTP PATCH) work out of the box!
The format of the URL that will be called for the PATCH request is baseurl/{id of the changed record}. The country API from above does not support writing back, however the url for writing back would be https://restcountries.eu/rest/v2/all/12 for the country with id 12. A sample body, in case the population in Afghanistan would change can be seen in the following sample. In this case the id column on the list element would be 'name'.
[
{
"name":"Afghanistan",
"population":28000000
}
]