REST API Data Connection

Step 1: Create a REST API connection at Global or App scope

1. Go to Connections → Data Sources either at Global or App Level.

2. Define a new REST API connection.

3. Provide API Base URL and Authentication details. For more details see Create Database Connections.

Step 2: Create Solution Data Connection

Follow below steps to configure the data connection as per required operation (Create, Read, Update or Delete) and as per Data needed from the API system.

1. Create a new or open an existing Form Solution and click on Add Data Connection from Solution ribbon menu.

2. Provide it a name and select type REST API. This will show all data sources of type “Rest API” which exists either in current App scope or Global scope.

3. Set API URL or REST API End point:

   1. By default, it shows the Base API URL, as defined while creating the Data Connection. Configure this URL as per requirement to get data from a specific end point.

   2. Click on three dots to open URL builder to add URL parts.

   3. In URL Builder dialog, add URL as needed for this solution data connection. it could be a fixed value or Form field value or both. Below is an example of getting specific Product details from SAP HANA API.

      1. Base URL as defined in connection: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap

      2. First URL Part to specify access to product API: /API_PRODUCT_SRV/A_Product/

      3. Second URL part to specify Product Number from a form field: ('[/my:myFields/my:Search_Product_Id]') NOTE: This value is as per SAP HANA API specification i.e. ('<<Product Number>>')

      4. Final URL will look like:

         https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_PRODUCT_SRV/A_Product/('[/my:myFields/my:Search_Product_Id]')

   Fallback to API URL defined in Data Connection library works if no API-URL defined with control (Lookup/Query/Drop-down)

   If API URL is changed in Data Connection library, it gets reflected in run-time solution as well.

   Data Connection added from Data Connection library is non-editable from Solution Data Connection level. User can only edit the API URL from filter property (Raw where clause) of Lookup/Query/Drop-down control.

   Following priority will be followed:

   • For Data Connection Library Connection

     • API URL defined in Query/Lookup control will be respected first.

     • In no API URL defined in Query/Lookup, it will fallback to API URL defined in Data Connection Library level.

   • For Solution Connection

     • API URL defined in Query/Lookup control will be respected first.

     • In no API URL defined in Query/Lookup, it will fallback to API URL defined in Solution Connection level.

4. HTTP Operations: REST API uses HTTP Verb to specify that the request is for Read/Update/Delete or Create. Select this field as per current API connection usage. Supported operations are:

   1. GET: To get data from API.

   2. Put / Patch: To update data.

   3. Post: To Create data.

   4. Delete: To Delete data.

      Note:

      Notes:

      • Select the above operation as per API specification of the system, as some systems may not follow standard HTTP verb. i.e. Post operation might be doing deletion of data.

      • Data Connection Adapter Plugin - Runner Node is supported with REST API Data Connection.

5. Set API Schema:

   1. Input Schema: Input schema is for the data that will be sent to API (i.e. Request payload in JSON). Provide JSON schema either from file or directly copy to text field.

   2. Output Schema: Output schema is for the data that will be received from the API (i.e. Response payload in JSON). Provide JSON schema either from file or directly copy to text field.

      For more information, refer steps to update Input/Output Schema for REST API connection.

   3. Error Schema: In case of error or exception some API return data in different JSON schema i.e. HTTP status code (4xxx or 5xxx) are considered as error / exception in API call. Provide JSON schema either from file or directly copy to text field.

   4. Request Header: This is the header data in Key Value pairs format. Request header is the data that will be sent to API in Request Headers section. Specify the expected request headers as per API specification. Also both key and value can be configured to read from Form fields or fixed value or both.

      Example: If request header authorization is set with value – bearer [FormFieldName], then at run time if FormFieldName value is 1234, then request header authorization value will be - bearer 1234

      Here bearer is a fixed value and FormFieldName is a Form Field.

   5. Response Header: This is the header in Key Value pairs format. Response header is the data that will be received from the API as response in headers section. Specify the expected request headers as per API specification. Key name should be fixed / static value provided at design time of solution, and the value will be a Form field and this form field will be updated with the value as per the data received from API. Response headers will only work with Web service run (Web service control or Data connection adapter).

      Note for Request Headers

      Below are the details of Support of header via Form field:

      1. Async data connection: Automatically retrieve data when form is opened is not checked, This is not supported.

      2. Sync data connection: Automatically retrieve data when form is opened is checked. This is supported only for non-repeating fields.

      Note:

      Notes:

      • If the REST API Data Connection (Sync/Async) is used in dropdown with Filter defined and user changes the Data Connection, a warning message is displayed. Based on the selection, the Data Connection mode changes and filters are cleared. Respective filter dialog (sync filter or REST API URL filter) opens for where Rest API Data Connection is consumed.

      • No warning message is displayed if the REST API Data Connection used in dropdown with no Filter is defined.

      JSON Payload field data type:

      Application can determine the JSON fields data type if JSON schema specified in Input / Output / Error schema has specified the Data Type name in value. i.e. to specify the field CityName as string type : { “CityName”:”string”} or to specify the field CreatedOn as Date type: {“CreatedOn”:”date”}. Below is the field type mapping table for reference:

      Data Type	Field Type
      int, bigint	For Number field.
      string	For string or Text field.
      decimal	For Decimal field.
      bit, bool, true	For Boolean field.
      date, datetime	For Date field.

      If no data type is specified then application tries to predict the datatype based on given value. Number value to int (i.e. 0 or 12 etc), Decimal value to double (i.e. 12.4 or 9.1 also 0.0 will be considered as int), Date value to date. It is recommended to specify the data type to get more defined results.

      Array Support

      Array type properties are also supported. Below is an example of array property and its data type notation. For array type properties the Form schema is generated as single column table (i.e. Repeating section with single form’s field)

      [{
      "id": "int",
      "name": "string",
      "productType": "string",
      "sizes": ["string"],
      "otherDetails": {
      "colors": ["string"],
      "versions": ["int"]
      }}]

      Date-type mismatch on Field Generate

      If the API field given in payload doesn't match with form field type (mainly use case with Date and Numbers) i.e. API field type is string, but it is mapped with Form field of type date or via versa; in such cases data conversation may not be correct as application will consider the data received from API server is string but Form will treat it like date so it may cause data mismatch or unknown errors.

      JSON payload provided is processed as case sensitive and all the key name provided are processed with same case as given. i.e “id”:”int” application will look for key with exact name case “id” and will not be able to process if the data received like “Id” or “ID” etc.

   6. Save the connection and it will appear in Solution's Data Connections.

Editing Data Connection (REST API):

If the Data Connection is in use, only the following properties will be editable.

• URL

• Request/Response Headers

Step 3: Mapping of API Solution Data Connection with Form Fields

This step is for mapping the API solution Data Connection’s Data fields with Form fields. It is same as mapping of Web Service or Reference Data connection fields with Form fields.

Below are the steps for mapping of API Solution data connection with Form fields:

1. Right click on Solution Data connection and choose option Create Form Fields.

2. In Field Mapping dialog provide below details:

   1. Description: A text note for this mapping.

   2. Group Name: Group name for Form schema fields. All Form fields will be created within this group only.

   3. Web Service Name: A Mapping Name which will be used in Form control or plugins.

   4. Click Next on this dialog.

3. The Field Mapping Parameters dialog will show all API Solution Data connection fields and Form fields, similar to what is shown for Web Service field mapping dialog.

4. Review or change the form field type or max length as per requirement.

5. Click OK to complete the mapping.

Mapping any Schema Field with different type of Form Field should be done in Field Mapping dialog. Changing the Form Field Type from Properties would not change the Data Type in WSDL.

For example:

In case of some GET API method there is a Date Field in Output Schema and its Data Type is String. The user should select Date Type in the Field Mapping dialog.

Step 4: Design the Form

Design the Form with the fields created and mapped to API Solution Data connection. Also put Form controls (i.e. Web Service, lookup, query or dropdown) which will execute the API Data connection.

1. Design the Form fields on Form View.

2. Place the Web Service and Button control on Form view. Configure the Web service control and button control to run the API solution data connection upon clicking this button.

3. Deploy the solution.

Step 5: Test the API Solution data connection

Launch the form and run the API Solution Data connection.

1. Launch the Form.

2. Click on the configured button to run the API Solution Data connection.

3. Form will execute the API and will show the response data on mapped Form fields.

[  {
"id": 1,
"name": "100-100",
"productType": "A1",
"weightUnit": "W1",
"netWeight": 90,
"grossWeight": 100,
"validityStartDate": "2020-10-03T10:28:45.892275+05:30"
},
{
"id": 2,
"name": "100-200",
"productType": "A1",
"weightUnit": "W1",
"netWeight": 100,
"grossWeight": 150,
"validityStartDate": "2019-08-30T10:28:46.3904638+05:30"
}
]