Creating a Data API

Overview

ROMA Connect allows you to define a data source as a backend service so that data can be read from or written to the data source and exposed to external systems through APIs.

Prerequisites

• Data sources have been connected to ROMA Connect. For details, see Connecting to Data Sources.
• If a backend service needs to use a signature key for authentication, create a signature key first.
• If you need to use the custom mode for API security authentication, create a custom authorizer first.
• Each line of record stored in a data source should not exceed 2 KB, or custom backend exceptions will occur.
• If a numeric value returned by the data source is zero with more than six decimal places, the data backend displays the value in scientific notation. Do not set the precision of numeric data to more than six decimal places.

Procedure

1. Log in to the ROMA Connect console. On the Instances page, click View Console of an instance.
2. Create a backend.
   1. In the navigation pane on the left, choose API Connect > Custom Backends. On the Backends tab page, click Create Backend.
   2. On the Create Backend page, set backend parameters and click Create.

      Table 1 Backend request information

      Parameter	Description
      Name	Enter a backend name. It is recommended that you enter a name based on naming rules to facilitate search.
      Integration Application	Select the integration application to which the backend belongs. If none is available, click Create Integration Application on the right to create one.
      Backend Request Method	Select the request method of the backend. The value can be GET, POST, PUT, or DELETE.
      Backend Request Path	Enter the request path of the backend, in the /getUserInfo/userId format. The value of Request Path is case sensitive.
      Backend Security Authentication	Select the security authentication mode of the backend. Signature key: A signature key is used to authenticate the request sender. If a signature key is used for authentication, the same signature key must be bound to the API that calls the backend service. None: No authentication is required for calling requests.
      Description	Enter a brief description of the backend.
      Advanced Settings
      Version	Enter the backend version, for example, V1.0. Custom backend version numbers differentiate the backend services.
      Input Parameters	Define request parameters of the backend service. In the Input Parameters area, click Add Input Parameter and add request parameters of the custom backend. Name: name of a request parameter, which is user-defined. Parameter Location: location of the request parameter in the backend request. The value can be Headers or Parameters. Default Value: default value of the parameter, used only in the subsequent custom backend test procedure. This parameter does not take effect during custom backend deployment. Mandatory: whether a request parameter is mandatory in a backend request. Description: Enter the description of the parameter.
      Returned Type	Select the response data format of the backend. The value can be JSON, XML, or STREAM.
      Formatting	This parameter specifies whether to format the response message body based on the selected return type.

      After the backend is created, the online IDE of the backend is automatically displayed. The backend type is data backend by default.

3. Configure a data backend.
   1. Click Add Data Source on the left of the online IDE.
   2. On the Add Data Source page displayed, configure data source information and click Add.

      Table 2 Data source configuration

      Parameter	Description
      Select Data Source	Select a data source that you configured in Connecting to Data Sources.
      Select Statement Type	Select the type of a statement to be executed. The value can be SQL or SP. If the Redis or MongoDB data source is used, select SQL. The actual statement is NoSQL.
      Advanced Settings
      Returned Object	Enter the name of the returned object. The execution result of the statement is encapsulated in the object and returned.
      Paging	This parameter indicates whether the statement execution results are returned on multiple pages. If multiple data sources are added to the same data backend, you cannot set Paging. If paging is enabled, you can add the query parameters pageNum and pageSize to the backend request to page the query results and specify the page number of the data to be returned. pageNum: page number of the data to be returned. The value starts from 1. pageSize: number of data records on each page. The structure of the response result varies depending on whether paging is enabled or disabled. For details, see Example of Paging Results. NOTE: A maximum of 2000 data records can be obtained if paging is enabled. If there are more than 2000 records, try using the offset and limit parameters in the execution statement. If Precompiling is disabled, the following is an example: select * from table01 limit ${limit} offset ${offset} Values of the offset and limit parameters can be transferred in the headers, parameters, or body of backend requests. Data sources with precompiling enabled need to convert offset and limit values by calling functions. For details, see Developing Custom Data Backends.
      Precompiling	This parameter specifies whether to precompile execution statements to prevent SQL injection risks.

      Example of Paging Results

      If Returned Object is set to mydata, five data records are returned after the statement is executed to query data from the data source.

      • If Paging is not enabled, all five data records are returned as the response result to the user. The following is an example of the response result.

        {
          "mydata": [
            {
              "id": 1,
              "name": "aaa"
            },
            {
              "id": 2,
              "name": "bbb"
            },
            {
              "id": 3,
              "name": "ccc"
            },
            {
              "id": 4,
              "name": "ddd"
            },
            {
              "id": 5,
              "name": "eee"
            }
          ]
        }
      • When Paging is enabled, if pageNum is set to 1 and pageSize is set to 2, the five data records queried by the statement will be displayed on multiple pages based on pageSize, with two data records on each page. Only the two data records on the first page will be returned to the user as the response result based on pageNum. In the response result, total indicates the total number of data records queried by running the statement, that is, 5. Response example:

        {
          "mydata": {
            "total": 5,
            "data": [
              {
                "id": 1,
                "name": "aaa"
              },
              {
                "id": 2,
                "name": "bbb"
              }
            ],
            "pageSize": 2,
            "pageNum": 1
          }
        }
   3. After adding a data source, select the data source on the left of the online IDE, and then add an execution statement for the data source in the editing box on the right.

      For details, see Developing Custom Data Backends.

      For the Redis or MongoDB data source, data processing commands of Redis or MongoDB are used.

   4. Click Save in the upper right corner of the page to save the backend configuration.
4. Test the backend functions.
   In the upper right corner of the page, click Test. In the Test Parameters area, add request parameters based on the definition of the backend service and click Test to send the request.

   • In the Execution Result area, view the response of the backend.
   • In the Execution History area, view the historical test records of the backend. Click a test record to import historical test parameters to the test parameter list on the left and perform the test again.
5. Deploy the backend.

   After the backend test is complete, click Deploy in the upper right corner of the page. In the dialog box displayed, click Yes to deploy the backend.

6. Publish a data API.
   1. Click Publish in the upper right corner of the page.
   2. On the page displayed, configure API information and click Publish to create a frontend data API for the backend and publish the API in the environment.

      Table 3 Parameters for publishing an API

      Parameter	Description
      API Group	Select an API group for the frontend API. If none is available, click Create API Group on the right to create one. NOTE: The API group cannot be changed once set and is bound to the access domain name of the API.
      Environment	Select the environment in which the API is to be published. If your required environment is not available, click Create Environment on the right to create one.
      Frontend Security Authentication	Select the authentication mode of the API. The App authentication mode is recommended. App: ROMA Connect authenticates API requests. When calling an API, a user gets authenticated using the key and secret of an integration application. IAM: IAM authenticates API requests. When calling an API, a user gets authenticated using the token or AK/SK. Custom: The custom function API is used for authenticating API requests. None: Authentication is not required for API requests.
      Custom Authorizer	This parameter is mandatory only if Frontend Security Authentication is set to Custom. Select a frontend custom authorizer you have created.
      Frontend Request Protocol	Select the request protocol used by the frontend API. The value can be HTTP, HTTPS, or HTTP&HTTPS. HTTPS is recommended for transmitting important or sensitive data.
      Timeout (ms)	Enter the timeout interval of a backend service request. The default value is 60000.
      Retry Times	Number of retry times after ROMA Connect fails to call the backend service. If the value is -1, the retry function is disabled. However, requests will be retried once by default except for those using POST and PATCH. If the value ranges from 0 to 10, this parameter is enabled, and retries are performed based on the configured value.
      Advanced Settings
      Frontend Request Method	Select the request method of the frontend API. ANY indicates that the API can be accessed using any request method.
      Frontend Request Path	Enter the request path of the frontend API, for example, /getUserInfo/userId. The value of Request Path is case sensitive.
      CORS	This parameter specifies whether CORS is supported for the API. For security purposes, the browser restricts the cross-domain requests from being initiated from a page script. In this case, the page can access only the resources from the same source. CORS allows the browser to send XMLHttpRequest requests to the server in a different domain. For details about CORS, see Configuring CORS for APIs.