edit-icon download-icon

Call Methods

Last Updated: Mar 29, 2018

The APIs of the API Gateway are called by sending HTTP GET requests to the API server address of the API Gateway, with corresponding request parameters included in the requests according to the interface instructions. The system returns processing results according to the request processing status.

Request structure

Service address

The API service access address of the API Gateway is apigateway.[RegionId].aliyuncs.com.

Example: apigateway.cn-hangzhou.aliyuncs.com

Communication protocols

The system supports communication requests through the HTTP or HTTPS channel. We recommend that you send requests over HTTPS for enhanced security.

Request methods

The system allows you to send HTTP GET requests. This requires request parameters to be included in the request URL.

Request parameters

For each request, the operation to be executed must be specified, namely the Action parameter (for example, CreateApi), and each operation must contain the public request parameters and the specific request parameters of the specified operation.

Character encoding

Requests and return results are encoded using the UTF-8 character set.

Public parameters

Public request parameters

Public request parameters are the request parameters that every interface must use.

Name Type Required? Description
Format String No Type of the return value in JSON or XML format. The default type is XML.
Version String Yes API version, in the format of YYYY-MM-DD. The current version is 2016-07-14.
AccessKeyId String Yes AccessKey ID issued by Alibaba Cloud to you for service access
Signature String Yes Signature result string. For more information about the signature calculation method, see the signature description.
SignatureMethod String Yes Signature method. Currently, HMAC-SHA1 is supported.
TimeStamp String Yes Request timestamp. The date format follows the ISO8601 standard and uses UTC time. The format is YYYY-MM-DDThh:mm:ssZ. Example: 2014-11-11T12:00:00Z (November 11, 2014 at 20:00:00, Beijing time)
SignatureVersion String Yes Signature algorithm version. The current version is 1.0.
SignatureNonce String Yes Unique random number, which is used to prevent network replay attacks. Different random numbers must be used for different requests.

Request example:

  1. https://apigateway.cn-hangzhou.aliyuncs.com/?Format=xml
  2. &Version=2016-07-14
  3. &Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
  4. &SignatureMethod=HMACSHA1
  5. &SignatureNonce=15215528852396
  6. &SignatureVersion=1.0
  7. &AccessKeyId=key-test
  8. &TimeStamp=2016-08-08T08:00:00Z

Public return parameters

Each time you send a request to call an interface, the system returns a unique identification code (RequestId), whether the request is successful.

Example of return results in XML format:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!—Result root node-->
  3. <Interface name+Response>
  4. <!—Return request tag-->
  5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
  6. <!—Return result data-->
  7. </Interface name+Response>

Example of return results in JSON format:

  1. {
  2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  3. /* Return result data*/
  4. }

Return results

After the API service is called, the returned data adopts a uniform format. A returned HTTP status code of 2xx indicates that the call was successful. A returned HTTP status code of 4xx or 5xx indicates that the call fails.

For a successful call, the primary formats of returned data are XML and JSON. When a request is sent, an external system can input parameters to specify the format of returned data. The default format is XML.

In this document, examples of return results are formatted in a way that is easier for you to view. The actual results returned are not formatted with line breaks, indentation, and so on.

Successful results

Example of return results in XML format:

(XML results returned include a message indicating whether the request is successful and the specific service data.)

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!—Result root node-->
  3. <Interface name+Response>
  4. <!—Return request tag-->
  5. <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId>
  6. <!—Return result data-->
  7. </Interface name+Response>

JSON example:

  1. {
  2. "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
  3. /* Return result data*/
  4. }

Error results

When an error occurs in an interface call, no results are returned. The caller can refer to the appendix to locate the cause of the error.

When an error occurs in a call, an HTTP status code 4xx or 5xx is returned for the HTTP request. The returned message body contains the specific error code and error message. The message body also contains the globally unique RequestId and the requested HostId. If unable to locate the error cause, the caller can contact Alibaba Cloud customer service and provide the HostId and RequestId to help us solve the problem as quickly as possible.

XML example:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <Error>
  3. <RequestId>8906582E-6722-409A-A6C4-0E7863B733A5</RequestId>
  4. <HostId>apigateway.cn-hangzhou.aliyuncs.com</HostId>
  5. <Code>InternalError</Code>
  6. <Message>The request processing has failed due to some unknown error.</Message>
  7. </Error>

JSON example:

  1. {
  2. "RequestId": "8906582E-6722-409A-A6C4-0E7863B733A5",
  3. "HostId": "apigateway.cn-hangzhou.aliyuncs.com",
  4. "Code": "InternalError",
  5. "Message": "The request processing has failed due to some unknown error."
  6. }
Thank you! We've received your feedback.