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.

Procedure

1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
2. Create a backend.
   1. In the navigation pane on the left, choose API Connect > Custom Backend. On the Backends tab page, click Create.
   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 no integration application 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	Select the backend version, for example, 1.0.
      Input Parameters	Define request parameters of the backend service based on the site requirements. 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: It is used as the default test value of parameters only in the subsequent custom backend test procedure. This parameter does not take effect during custom backend deployment. Mandatory: specifies 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.
      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 Data API Statements.

      For the Redis or MongoDB data source, the data processing command of Redis or MongoDB is used.

      NOTE:

      If an SQL statement references backend request parameters of multiple data types at the same time, ROMA Connect converts the input parameters to the String type by default. Therefore, when you execute the SQL statement, invoke the corresponding function to convert the data type of a non-String parameter.

   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 the API group to which the corresponding API belongs. If no API group is available, click Create API Group on the right to create one.
      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.
      Backend Security Authentication	Select the authentication mode of the API. The App authentication mode is recommended. App: ROMA Connect authenticates API requests. When a user calls the API, the key and secret of the integration applications are used for authenticating API requests. IAM: IAM authenticates API requests. When a user calls an API, the token or AK/SK is used for authenticating API requests. 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.
      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, in the /getUserInfo/userId format. 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.