Opening Data Through Data APIs

Prerequisites

• The network where the service system is located can communicate with the network of ROMA Connect.

  If the ROMA Connect instances communicate with each other through the public network, an elastic IP address (EIP) must be bound to each instance.

• The data source type of the service system database is supported by ROMA Connect.

  For details about the data sources supported by data APIs, see Data Sources Supported by Data APIs.

• Prepare an available independent domain name as the access domain name of the API.

  You have configured domain name resolution from the independent domain name to the APIC connection address. For details, see Adding an A Record Set.

  If you do not have an independent domain name, you can apply for a domain name from the domain name registrar.

• If the data API uses the HTTPS request protocol, you need to apply for an SSL certificate for the independent domain name and obtain the SSL certificate content and key in PEM format.

Exposing the Data API of the Service System

1. Create an integration application.

   All resources in the ROMA Connect instance must belong to an integration application. Before creating other resources, make sure an integration application is available. If an integration application is available, skip this step.

   1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
   2. In the navigation pane on the left, choose Integration Applications. In the upper right corner of the page, click Create Integration Application.
   3. In the dialog box displayed, set Name and click OK.
2. Connect to a data source.
   Configure the connection between ROMA Connect and service system databases to read data from the databases. The access configuration varies depending on the data source type. The MySQL database is used as an example. For details about how to access other types of databases, see Connecting to Data Sources.

   1. In the navigation pane on the left, choose Data Sources. In the upper right corner of the page, click Access Data Source.
   2. On the Default tab page, select MySQL and click Next.
   3. Configure the data source connection information.

      Table 1 Data source connection information

      Parameter	Description
      Name	Enter a custom data source name. Using naming rules facilitates future search.
      Integration Application	Select the integration application to which the data source belongs.
      Description	Click to edit the description of the data source.
      Connection Mode	Select a database connection mode. Default: The system automatically concatenates data source connection character strings based on your configured data. Professional: You need to enter a data source connection string in JDBC format.
      Connection Address	Mandatory for Connection Mode set to Default. Enter the IP address and port number for connecting to the database.
      Database Name	Mandatory for Connection Mode set to Default. Enter the name of the database to be accessed.
      Encoding Format	Available for Connection Mode set to Default. Enter the encoding format used by the database.
      Timeout Interval(s)	Available for Connection Mode set to Default. Enter the timeout interval for connecting to the database, in seconds.
      Connection String	Mandatory for Connection Mode set to Professional. Enter the JDBC connection string of the MySQL database, for example, jdbc:mysql://{hostname}:{port}/{dbname}. {hostname} indicates the connection address of the database. {port} indicates the port number for connecting to the database. {dbname} indicates the name of the database to be connected.
      Username	Enter the username for connecting to the database.
      Password	Enter the password for connecting to the database.

   4. After setting the parameters for the MySQL data source, click Check Connectivity to test the data source connectivity.
      • If the test result is Data source connected successfully, go to the next step.
      • If the test result is Failed to connect to the data source, check and modify the connection parameters, and click Recheck until the connection is successful.
   5. Click Create.
3. Create a data backend.
   You can customize a backend to convert the data of a service system into a backend service.

   1. In the navigation pane on the left, choose API Connect > Custom Backends. On the Backends tab, click Create Backend.
   2. On the Create Backend page, set backend parameters and click Create.

      Table 2 Backend request information

      Parameter	Description
      Name	Enter a backend name. Using naming rules facilitates future search.
      Integration Application	Select the integration application to which the backend belongs.
      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, for example, /getUserInfo/userId. The 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. Customized backend version numbers differentiate backend services.
      Input Parameters	Define request parameters of the backend service based on site requirements. In the Input Parameters area, click Add Input Parameter to 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 returned type.

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

   3. On the Online IDE tab page, choose File > New Data Backend > Add Data Source.
   4. On the Add Data Source page displayed, configure data source information and click Add.

      Table 3 Data source configuration

      Parameter	Description
      Select Data Source	Select a data source that has been created in Access Data Source.
      Select Statement Type	Select the type of the 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, the Paging parameter is not available.
      Precompiling	This parameter specifies whether to precompile execution statements to prevent SQL injection risks.

   5. After adding a data source, you can select the data source on the left of the IDE and add an execution statement in the statement editing box on the right to obtain the data to be returned.
      • Data backends support standard SQL syntax. For details about the syntax differences, see Developing Custom Data Backends.
      • For the Redis or MongoDB data source, the data processing command of Redis or MongoDB is used.
      

      If an SQL statement references backend request parameters of multiple data types, ROMA Connect converts the input parameters to the String type by default. Therefore, when the SQL statement is executed, the corresponding function needs to be called to convert non-String parameters.

   6. Click Save in the upper right corner of the page to save the backend configuration.
   7. 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. On the Execution Result tab page on the right, check whether the expected data is returned.

   8. After the backend is tested, click Deploy in the upper right corner of the page. In the dialog box displayed, click OK to deploy the backend.
4. Publish the data API.
   Publish the data backend as a data API and deploy the API in the environment so that other service systems can call this 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 API for the backend and publish the API in an environment.
      After the API is published, the API details page is displayed.

      Table 4 Parameters for publishing an API

      Parameter	Description
      Group	Select an API group for the frontend API. If no API group is available, click Create API Group on the right to create one.
      Environment	Select the environment in which the frontend API will be published. Select the default environment RELEASE when exposing an API.
      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 a token or an AK/SK pair. Custom: The custom function API is used for authenticating API requests. None: Authentication is not required for API requests.
      Custom Authorizer	Mandatory for Frontend Security Authentication 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 HTTPS, HTTP, 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.
      Retries	Number of retries after ROMA Connect fails to call the backend service. If the value is -1, this parameter is disabled. 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 supports any request method. Generally, the API used to obtain database data uses the GET method.
      Frontend Request Path	Enter the request path of the frontend API, for example, /getUserInfo/userId. The request path is case sensitive.
      CORS	Whether to enable CORS for the API. For security purposes, a browser restricts cross-domain requests initiated from scripts. That is, only resources from the same domain can be requested. CORS allows the browser to send XMLHttpRequest requests to the server in a different domain. For details about how to call APIs for cross-domain access, see Configuring CORS for APIs.

5. Bind an independent domain name to the data API.
   1. On the API details page displayed after you publish the API, choose Group Information and click Bind Independent Domain Name in the Independent Domain Names area.
   2. In the displayed dialog box, enter the domain name and click OK.

      Table 5 Independent domain name configuration

      Parameter	Description
      Domain Name	Enter the domain name to be bound.
      Minimum TLS Version	The minimum TLS version that can be used to access the domain name.
      HTTP-to-HTTPS Auto Redirection	Whether to support HTTP-to-HTTPS redirection. Redirection takes effect only when the API request protocol is HTTPS or HTTP&HTTPS and an SSL certificate has been bound to the independent domain name. NOTE: Redirection is only suitable for GET and HEAD requests. Redirecting other requests may cause data loss due to browser restrictions.

   3. (Optional) For HTTPS-compatible data APIs, bind an SSL certificate to their independent domain name.
      1. Click Select SSL Certificate on the right of the independent domain name.
      2. Select an SSL certificate and click OK.

         If none is available, click Create SSL Certificate to create one.

Calling an API from Other Service Systems

1. Obtain the API calling information from the API provider.
   • Obtain the request information of the API.

     On the ROMA Connect console, choose API Connect > APIs. In the API list, click the API name to go to the details page and obtain the API request method and access address. Click Frontend Configuration in the lower part of the page and obtain the API request parameters.

   • Obtain the authentication information of the API.
     The authentication information to be obtained varies with the API authentication mode.

     • App authentication:
       • Signature authentication: Obtain the key and secret of the credential authorized by the API provider and the SDK for calling the API.
       • Simple authentication: Obtain the AppCode of the credential authorized by the API from the API provider.
       • Others: Obtain the key and secret of the credential authorized by the API from the API provider.
     • IAM: The account credential (password or AK/SK) of the cloud service platform is used for authentication. If the AK/SK is used for authentication, you also need to obtain the SDK from the API provider.
     • Custom authentication: Obtain the custom authentication information to be carried in the request parameters from the API provider.
     • None: No authentication information is required.
2. Assemble and send API requests based on the obtained API calling information to obtain required data.