Opening Data Through Function 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 function APIs, see Data Sources Supported by Service Integration.

• 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 function 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 Function 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. Create a function 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 1 Backend request information

      Parameter	Description
      Name	Enter a custom 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. In the upper left corner of the online IDE, choose File > New Function Backend > MySQL Calling Example. In the dialog box displayed, click Yes to switch the backend to a function backend.

      If the Redis or MongoDB data source is used, select Redis Calling Example.

   4. In the statement editing box on the right, modify the data source access configuration based on the function script example provided by the system.

      importClass(com.roma.apic.livedata.client.v1.DataSourceClient);
      importClass(com.roma.apic.livedata.config.v1.DataSourceConfig);
      function execute(data){
      var config = new DataSourceConfig()
        config.setType("mysql")
        config.setUrl("jdbc:mysql://127.0.0.1:3306/db?allowPublicKeyRetrieval=true")
        config.setUser("xxxx")
        config.setPassword("xxxx")
        var ds = new DataSourceClient(config)
        return ds.execute("SELECT * FROM person where name = ? and age = ?","Tom",20);
      }
      • Configure the data source connection information in setType, setUrl, setUser, and setPassword. For details about the parameter configuration, see DataSourceConfig.
      • Set the SQL statement in ds.execute to obtain the data to be returned.
   5. Click Save in the upper right corner of the page to save the backend configuration.
   6. 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.

   7. After the backend is tested, click Deploy in the upper right corner of the page. In the dialog box displayed, click Yes to deploy the backend.
3. Publish the function API.
   Publish the backend as a function API and deploy it in the environment so that other service systems can call it.

   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 2 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.

4. Bind an independent domain name to the function 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 3 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 function APIs, bind an SSL certificate to their independent domain name. Otherwise, skip this step.
      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.