Web API Data Sources

Web API Data Sources allow you to interact with remote RESTful Web APIs via NDL's Connect product. Connect acts as a gateway between your Digitise app and the Web API, providing simplified access to the Web API service within your app.

 

In order to access a Web API through Connect, the Web API must have an OpenAPI definition file which describes the API (Application Programming Interface) - that is, the interface through which external applications can interact with the Web API. The API provides one or more 'operations' offered by the Web API service, each of which defines an action or task which the Web API software can perform. To initiate one of the available operations, your app will send a request to the Web API in the format defined by the Web API for that operation. The request may contain one or more parameters specifying any data required by the operation in order for it to perform its function. Once the function has been completed, the operation may send a response back to your app, which may include an error code/message if the operation fails. Once again, the format of the response, and whether there is one or not, will be determined by the operation's definition. A comprehensive list of response codes can be found at the following location:

 

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

 

The OpenAPI definition file, contains a list of the operations for the Web API it describes and defines the parameters which can be included in the requests and any data items in any responses. Some of the request parameters may be required, i.e., they must always be included, whereas others may be optional, which means they can be omitted if not needed. Connect reads this definition file and interprets the structure of the Web API's operations for you. For each operation it produces one or more tables which list the data items which can appear in the request and response messages. There will be separate tables for the request and response data and the data items for either or both can be spread over multiple tables. If an operation doesn't send a response, there will only be request table(s).

When you import an operation into your Digitise Apps Project, these tables represent the tables which will be created at runtime in the local database on the device to hold the data associated with this operation. So, your app will need to write the data into the request table(s) which will be populated into the request message parameters before the request is sent to the Web API and data received back in the response will be written to the response table(s).

This means that within your Project, you can create a Data Source, map data to Controls and upload and download data as easily as you can for a remote database. You don't need to interpret a Web API's definition file or correctly format the HTTP posts or extract relevant data from an operation's responses. Connect deals with all that for you.

For example, imagine you want to access a Web API which will return you a phone number if you supply the person's name and address. The user would enter the person's name and address which would be stored in the request table in the local database. Your app would then send this information to Connect and Connect would generate a suitable HTTP request message and send it to the operation over an internet, or other web, connection. The operation would send an HTTP response message back to Connect containing the phone number and Connect would extract the number from this response and forward it on to your app, where it would be stored in the response table(s) from where it could, for example, be displayed on a form for the user to see.

If a data item can hold more than one value at a time, i.e., it can hold an array of values, this data item will be given a separate table whereby each value can be stored in your app as a separate record. For example, suppose you have a Web API which allows you to record the outcome of a housing repairs visit and order any parts needed to complete any unfinished repairs and the operation expects all parts to be presented within the request as an array of part code values in a single parameter. In this sort of scenario, you might have at least two request tables - one general table to cover the main job report data and a second table to allow you to store all the parts being ordered to complete the job, with each part being stored in a separate record. When the request is sent to the Web API, Connect will combine the separate parts records into an array within the single parameter and include this parameter within the request message.

Connect also handles Web API security (including OAuth), storing the required security-related information on Hub Server, allowing Projects to be deployed without the need for details to be re-keyed or re-submitted each time a resource needs to be accessed.

 

Before you can incorporate Web API Data Sources for a RESTful Web API within your app, the Web API's OpenAPI definition file has to be imported and interpreted by Connect. Connect is separate to Digitise Apps and is part of NDL's Hub product. Therefore, importing Web API definition files is done using Hub Manager and is not part of Digitise Apps. For more information about importing and configuring OpenAPI definitions within Connect see the separate Hub Online Help.

Once a Web API's definition file has been imported and parsed by Connect, however, you can then interrogate Connect from within App Studio and display a list of that Web API's operations and import any you want to use within your app as Data Sources. Each operation you import will be a separate Data Source within your Project and as discussed above, will include one or more tables representing the request and response data items. You can then specify which of the data items in each table you want to use within your app, just as you can for any other type of Data Source. And, as with any other type of Data Source, you can ignore any data items that you don't need within your app, although you will need to include all required request parameters, otherwise the Web API service will not be able to action your request correctly. For example, in our previous example the user supplies a name and address. Now suppose that the address could include the first line of the address, the town/city, county and postcode but that only the first line of the address and the postcode are required parameters and the town/city and county parameters are optional. When you import the operation into your Digitise Apps Project, you could ignore the optional parameters and just include the first line of the address and postcode in the Data Source, if you don't need the town/city or county for anything else within the app.

Once you have added a Web API Data Source to your Project, the connection between your app and Connect is all handled automatically and you don't need to do anything beyond handling the data in the same way as for database Data Sources.