Calling an Open API

Overview

After an API is published in an environment, it can be called by other users. API calling operations vary by the authentication mode used by the API.

Prerequisites

Before calling an API, ensure that the network of your service system can communicate with the API access domain name or address.

• If the service system and the ROMA Connect instance are in the same VPC, the API can be directly accessed.
• Two VPCs in the same region: Connect the instance and the service system with a peering connection. For details, see VPC Peering Connection.
• Two VPCs in two regions: Create a cloud connection and load the VPCs that need to communicate with each other. For details, see Network Communications Among VPCs Across Regions.
• Communication over the public network: Ensure that the instance must be bound with an EIP.

Obtaining API Calling Information

Obtain the API calling information from the API provider before you call an API.

• Obtaining API request information

  On the ROMA Connect instance console, choose APIC > API Management. On the APIs tab page, obtain the domain name, request method, and request path of an API. Click the API name to go to the details page. On the API Calling tab page, obtain the request protocol, input parameters, and request body description of the API.

• Obtaining API authentication information

  Obtain the request authentication information according to the authentication mode used by an API.

  Authentication Mode	Authentication Info
  App authentication (with a signature)	Obtain the key and secret of the integration application (or client AppKey and AppSecret) authorized by the API from the API provider, as well as the SDK, for authentication signatures.
  App authentication (through simple authentication)	Obtain the AppCode of the client authorized by the API from the API provider.
  App authentication (with green channel whitelisting)	Obtain the key (or client AppKey) of the integration application authorized for the API from the API provider.
  App authentication (with app_secret)	Obtain the key and secret (or client AppKey and AppSecret) of the integration application authorized for the API from the API provider.
  App authentication (with app_basic)	Obtain the key and secret (or client AppKey and AppSecret) of the integration application authorized for the API from the API provider.
  App authentication (two-factor)	Obtain the authentication information required for App authentication and custom authentication.
  IAM authentication (with a token)	Obtain the username and password of the cloud service platform.
  IAM authentication (with AK/SK)	Obtain the AK/SK of the account on the cloud service platform and the SDK used for signatures.
  IAM authentication (two-factor)	Obtain the authentication information required for IAM authentication and custom authentication.
  Custom authentication	Obtain the custom authentication information to be carried in the request parameters from the API provider.
  None	No authentication information is required.

  • Obtaining the key and secret of an integration application

    On the ROMA Connect instance console, choose Integration Applications. Click the name of an integration application authorized by the API. On the details page that is displayed, obtain the key and secret of the application.

  • Obtaining the AppKey and AppSecret of a client

    On the ROMA Connect instance console, choose API Connect > API Calling. On the Clients tab page, click the name of a client bound to the API. On the client details page that is displayed, obtain the AppKey and AppSecret of the client.

  • Obtaining the SDK used for authentication signatures

    On the ROMA Connect instance console, choose API Connect > API Calling. Download the SDK of the required language on the SDK tab page.

  • Obtaining the AppCode

    On the ROMA Connect instance console, choose API Connect > API Calling. On the Clients tab page, click the name of a client bound to the API. On the client details page that is displayed, obtain the AppCode on the AppCode tab page.

Calling an API

1. Example API request

   POST https://{Address}/{Path}?{Query}
   {Header}
   
   {
     {Body}
   }
   • POST: request method. Use the actual request method obtained in Obtaining API request information.
   • {Address}: request address. Use the actual request address obtained in Obtaining API request information. You can also use an IP address to access an API.

     Scenario	API Request Parameter Configuration
     Using a domain name to call an API	ROMA Connect allows APIs to be called using the subdomain name assigned to the API group or the domain name bound to the API group. No additional configuration is required.
     Calling an API in the DEFAULT group with an IP address	Call an API in the DEFAULT group with an IP address. No additional configuration is required.
     Calling an API not in the DEFAULT group with an IP address	The app_route parameter described in Modifying Instance Configuration Parameters has been set to on for a ROMA Connect instance, indicating that an API can be called by using an IP address. ROMA Connect does not allow APIs in non-DEFAULT groups to be directly called using IP addresses. The header parameter X-HW-ID must be added to the request message, and the value must be the key or client AppKey of the integration application authorized by the API.

   • {Path}: request path. Use the actual request path obtained in Obtaining API request information.
   • (Optional) {Query}: query parameter in Parameter_name=Parameter_value format, for example, limit=10. Use & to separate multiple query parameters. For details, see the request parameters obtained in Obtaining API request information.
   • {Header}: request header parameter in Parameter_name:Parameter_value format, for example, Content-Type:application/json. For details, see the request parameters obtained in Obtaining API request information.
   • {Body}: request body in JSON format. For details, see the request body description obtained in Obtaining API request information.

2. Add authentication information for the API request.

   API Authentication Mode	API Request Parameter Configuration
   App authentication (with a signature)	Obtain the SDK to sign the API request. For details, see Developing API Calling Authentication (App).
   App authentication (through simple authentication)	Add the header parameter X-Apig-AppCode to the API request. The parameter value is the AppCode obtained in Obtaining API authentication information.
   App authentication (with green channel whitelisting)	Add the header parameter X-HW-ID to the API request. The parameter value is the key of the integration application authorized for the API or the client's AppKey.
   App authentication (with app_secret)	The app_secret parameter has been set to on on the Configuration Parameters tab page of a ROMA Connect instance, indicating that app_secret authentication is enabled. Add the header parameter X-HW-ID to the API request. The parameter value is the key of the integration application authorized for the API or the client's AppKey. Add the header parameter X-HW-AppKey to the API request. The parameter value is the secret or AppSecret obtained in Obtaining API authentication information.
   App authentication (with app_basic)	The app_basic parameter described in Modifying Instance Configuration Parameters has been set to on for a ROMA Connect instance, indicating that app_basic authentication is enabled. Add the header parameter Authorization to the API request. The value is "Basic "+base64(appkey+":"+appsecret). appkey and appsecret are the key and secret (or AppKey and AppSecret) obtained in Obtaining API authentication information.
   App authentication (two-factor)	An API request carries authentication information of both App authentication and custom authentication.
   IAM authentication (with a token)	Obtain the authentication token from the cloud service platform, add the header parameter X-Auth-Token to the API request, and set the value to the authentication token. For details, see Token Authentication.
   IAM authentication (with AK/SK)	Obtain the SDK to sign the API request. For details, see AK/SK Authentication.
   IAM authentication (two-factor)	An API request carries authentication information of both IAM authentication and custom authentication.
   Custom authentication	Based on the definition of custom authentication, the related authentication information is carried in the API request parameters for authentication.
   None	No authentication is required, and the API can be directly called.