All Products
Document Center

API Gateway:Examples on calling APIs

Last Updated:Feb 07, 2023

You can use API Gateway to call the API services enabled by other Alibaba Cloud users or third-party service providers. API Gateway provides a series of management and support services.

Call an API

You can use SDKs for multiple programming languages provided in the API Gateway console to call an API. For information about the SDKs, see the SDK page in the API Gateway console. You can also construct an HTTP or HTTPS request to call an API.

The following items describe the details and provide examples on API calls:

1. Requests

A request URL consists of a domain name and a path.

The domain name must be bound to the API group that contains the API to be called. If the domain name is not bound to the API group, a second-level domain name that is assigned by the system can be used.

Sample request method:


Sample request body:

FormParam1=FormParamValue1&FormParam2=FormParamValue2   # HTTP Request Body

Sample request header:

Date: Mon, 22 Aug 2016 11:21:04 GMT
User-Agent: Apache-HttpClient/4.1.2 (java 1.6)
Content-Type: application/x-www-form-urlencoded; charset=UTF-8 
# The type of the request body. Specify the request body type based on the actual request you want to make. 

Accept: application/json 
# The type of the response body. Some APIs can return data in the appropriate format based on the specified response type. We recommend that you manually specify the request header. If the request header is not specified, some HTTP clients use the default value */*. This may cause signature errors. 

X-Ca-Request-Mode: debug 
# Specifies whether to enable the debug mode. This parameter is not case-sensitive. If it is not specified, the debug mode is disabled. Enable this mode in the API debugging phase. 

X-Ca-Version: 1  
# The version number of the API. All APIs support only version 1. You can leave this request header unspecified. The default version number is 1. 

X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp 
# The custom request headers that are involved in signature calculation. The server reads the request headers based on this configuration to sign the request. This configuration does not include the Content-Type, Accept, Content-MD5, and Date request headers because these headers are included in the basic signature structure. For information about the signature, see Request signatures. 

X-Ca-Stage: RELEASE  
# The stage of the API. Valid values: TEST, PRE, and RELEASE. This parameter is not case-sensitive. The API provider can select the stage to which the API is published. The API can be called only after it is published to the specified stage. Otherwise, the system prompts that the API cannot be found or that the request URL is invalid. 

X-Ca-Key: 60022326  
# The AppKey of the request. You must obtain the AppKey in the API Gateway console. Applications can call APIs only after they are granted the permissions. By default, APIs that are purchased in Alibaba Cloud Marketplace have granted the permissions to applications. All Alibaba Cloud services use the same AppKey system. To prevent the impact on other Alibaba Cloud services that you activated, proceed with caution when you delete an AppKey. 

X-Ca-Timestamp: 1471864864235 
# The timestamp of the request. This value is a UNIX timestamp that represents the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. By default, the timestamp is valid for 15 minutes. 

# The unique ID of the request. AppKey, API, and Nonce must be unique within the last 15 minutes. To prevent replay attacks, you must specify both the X-Ca-Nonce header and the X-Ca-Timestamp header. 

X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys= 
# The signature of the request. 

CustomHeader: CustomHeaderValue  
# The custom request headers. CustomHeaderValue is used as an example. You can configure multiple custom request headers in a request based on the definition of the API that is being called.

2. Responses

Status code:

# The status code of the response. If the value is greater than or equal to 200 but less than 300, the call succeeded. If the value is greater than or equal to 400 but less than 500, a client-side error has occurred. If the value is greater than 500, a server-side error has occurred.

Response headers:

X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF 
# The unique ID of the request. When API Gateway receives a request, it generates a request ID and returns the request ID to the client in the X-Ca-Request-Id header. We recommend that you record the request ID in the client and backend server for troubleshooting and tracking. 

X-Ca-Error-Message: Invalid Url  
# The error message returned by API Gateway. If a request fails, API Gateway returns the error message to the client in the X-Ca-Error-Message header. 

X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}  
# The message returned only when the debug mode is enabled. The message is used only for reference at the debugging stage.

Regardless of whether you use HTTP or HTTPS to call an API, the request must include the signature information. The AppKey in the signature is used to verify your identity, and the AppSecret in the signature is used to encrypt and verify the signature string. For information about how to calculate and pass an encrypted signature, see Use digest authentication to call an API.

For information about the demos of signature calculation, see the SDK page in the API Gateway console.

For more information, see Overview.