Calling an Open API

Constraints

• If you use the default subdomain name to access an API, you can access the API a maximum of 1000 times every day.
• If there are two APIs with the same group, request method, and request path, the API with exact matching is first called.

Prerequisites

Before calling an API, ensure that the network of your service system can communicate with the API access domain name or address. This depends on where your service system is in relative to the ROMA Connect instance.

• The same VPC: Let the instance directly access the API.
• 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.

• Request information

  On the ROMA Connect instance console, choose API Connect > APIs and obtain the domain name, request method, and URL of an API. Click the API name to go to the details page. Click the Frontend Configuration tab on the APIs page, obtain the request parameters and request body of the API.

• Authentication information

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

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

  • Key and secret of a credential

    On the ROMA Connect instance console, choose API Connect > Credentials. Click the name of a credential authorized by the API. On the page displayed, obtain the key and secret of the credential.

  • SDK used for authentication signatures

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

  • AppCodes

    On the ROMA Connect instance console, choose API Connect > Credentials. Click the name of a credential authorized by the API. On the page displayed, obtain an AppCode of the credential in the AppCodes area.

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 of the credential authorized by the API.

   • {Path}: request path. Use the actual URL 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 obtained in Obtaining API authentication information.
   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 obtained in Obtaining API authentication information. Add the header parameter X-HW-AppKey to the API request. The parameter value is the secret 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 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)	Sign API requests using the obtained SDK. 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.