Constructing a Standard Request

Updated on 2025-01-24 GMT+08:00

View PDF

To access an API through AK/SK authentication, create a standard request, and then sign the request. The client must follow the same request specifications as API Gateway so that each HTTP request can obtain the same signing result from the frontend and backend to complete identity authentication.

The pseudocode of standard HTTP requests is as follows:

CanonicalRequest =
      HTTPRequestMethod + '\n' +
      CanonicalURI + '\n' +
      CanonicalQueryString + '\n' +
      CanonicalHeaders + '\n' +
      SignedHeaders + '\n' +
      HexEncode(Hash(RequestPayload))

The following procedure uses the Virtual Private Cloud (VPC) query API as an example to describe how to construct a standard request.

Original request:

GET https://service.region.example.com/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs?limit=2&marker=13551d6b-755d-4757-b956-536f674975c0 HTTP/1.1
Host: service.region.example.com
X-Sdk-Date: 20191115T033655Z

Specify an HTTP request method (HTTPRequestMethod) and end with a carriage return line feed (CRLF).

HTTP request methods include GET, PUT, POST, and so on. For example:
```
GET
```
Add a standard URI (CanonicalURI) and end with a CRLF.

Description

Path of the requested resource, which is the URI code of the absolute path.

Format

According to RFC 3986, each part of a valid URI except the redundant and relative paths must be URI-encoded. If a URI does not end with a slash (/), add a slash at its end.

Example

See the URI of each API in the API Reference of the corresponding cloud service. For example, the standard URI code of the VPC query API (/v1/{project_id}/vpcs) is as follows:
```
GET
/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs/
```
A URI must end with a slash (/) for signature calculation. However, the slash is not required when a request is sent.
Add a standard query string (CanonicalQueryString) and end with a CRLF.

Description

Query strings. If no query strings are configured, an empty string is used.

Format

Pay attention to the following to ensure valid query strings:
- Perform URI encoding on each parameter and value according to the following rules:
  - Do not perform URI encoding on any non-reserved characters defined in RFC 3986, including A–Z, a–z, 0–9, hyphen (-), underscore (_), period (.), and tilde (~).
  - Use %XY to perform percent encoding on all non-reserved characters. X and Y indicate hexadecimal characters (0–9 and A–F). For example, the space character must be encoded as %20, and an extended UTF-8 character must be encoded in the "%XY%ZA%BC" format.
- Add "URI-encoded parameter name=URI-encoded parameter value" to each parameter. If no value is specified, use an empty string instead. The equal sign (=) is required.
  For example, in the following string that contains two parameters, the value of parameter parm2 is null.
```
parm1=value1&parm2=
```
- Sort the parameters in alphabetically ascending order. For example, a parameter starting with uppercase letter F precedes another parameter starting with lowercase letter b.
- Construct a standard query string from the first parameter after sorting.
Example
The URI of the VPC query API contains two optional parameters: limit and marker. limit indicates the number of records displayed on each page, and marker indicates the start VPC ID for pagination query.
```
GET
/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs/
limit=2&marker=13551d6b-755d-4757-b956-536f674975c0
```
Add standard headers (CanonicalHeaders) and end with a CRLF.

Description

List of standard request headers, including all HTTP message headers in the to-be-signed request. The X-Sdk-Date header must be included to verify the signing time, which is in the UTC time format YYYYMMDDTHHMMSSZ as specified in ISO 8601.

CAUTION:

The local time on the client must be synchronized with the clock server to avoid a large offset in the value of the X-Sdk-Date request header.

API Gateway checks the time format and compares the time with the time when API Gateway receives the request. If the time difference exceeds 15 minutes, API Gateway will reject the request.

Format

CanonicalHeaders consists of multiple message headers, for example, CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + .... Each message header (CanonicalHeadersEntry) is in the format of Lowercase(HeaderName) + ':' + Trimall(HeaderValue) + '\n'.
- Lowercase is a function for converting all letters into lowercase letters.
- Trimall is a function for deleting the spaces before and after a value.
- The last message header carries a CRLF. Therefore, an empty line appears because the CanonicalHeaders field also contains a CRLF according to the specifications.
Example
Requests for calling the VPC query API need to contain the X-Sdk-Date, Host (cloud service endpoint), and Content-Type headers.
```
GET
/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs/
limit=2&marker=13551d6b-755d-4757-b956-536f674975c0
content-type:application/json
host:service.region.example.com
x-sdk-date:20191115T033655Z
```
NOTICE:
Valid message headers must meet the following requirements:
- All letters in a header are converted to lowercase letters, and all spaces before and after the header are deleted.
- All headers are sorted in alphabetically ascending order.
For example, the original headers are as follows:
```
Host: service.region.example.com\n
Content-Type: application/json;charset=utf8\n
My-header1:    a   b   c  \n
X-Sdk-Date:20190318T094751Z\n
My-Header2:    "x   y   \n
```
The message header names are converted into lowercase letters, the message headers are sorted in alphabetical order, and spaces before and after the header values are deleted. The standardized message headers are as follows:
```
content-type:application/json;charset=utf8\n
host:service.region.example.com\n
my-header1:a   b   c\n
my-header2:"x   y\n
x-sdk-date:20190318T094751Z\n
```
Add message headers (SignedHeaders) for request signing, and end with a CRLF.

Description

List of message headers used for request signing. This step is to determine which headers are used for signing the request and which headers can be ignored during request verification. The X-Sdk-date header must be included.

Format

SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ...

Letters in the message headers are converted to lowercase letters. All headers are sorted alphabetically and separated with commas.

Lowercase is a function for converting all letters into lowercase letters.

Example
In the following request, the Content-Type, Host, and X-Sdk-Date headers are used for request signing.
```
GET
/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs/
limit=2&marker=13551d6b-755d-4757-b956-536f674975c0
content-type:application/json
host:service.region.example.com
x-sdk-date:20191115T033655Z

content-type;host;x-sdk-date
```
The signed headers are as follows:
```
SignedHeaders=content-type;host;x-sdk-date
```
For details about how to add headers to a request, see Adding the Signature to the Request Header.
Use a hash function, such as SHA-256, to create a hash value based on the body (RequestPayload) of the HTTP or HTTPS request.

Description

Request message body. The message body needs two layers of conversion (HexEncode(Hash(RequestPayload))). Hash is a function for generating message digest. Currently, SHA-256 is supported. HexEncode is the Base16 encoding function for returning a digest consisting of lowercase letters. For example, HexEncode("m") returns 6d instead of 6D. Each byte you enter is expressed as two hexadecimal characters.

If RequestPayload is null, the null value is used for calculating a hash value.

Example

This example uses GET as an example, and the request body is empty. After hash processing, the request body (empty string) is as follows:
```
GET
/v1/77b6a44cba5143ab91d13ab9a8ff44fd/vpcs/
limit=2&marker=13551d6b-755d-4757-b956-536f674975c0
content-type:application/json
host:service.region.example.com
x-sdk-date:20191115T033655Z

content-type;host;x-sdk-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```
A standard request is constructed.
Perform hash processing on the standard request in the same way as that on the RequestPayload. After hash processing, the standard request is expressed with lowercase hexadecimal strings.

Algorithm pseudocode: Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))

Example of the standard request after hash processing:
```
b25362e603ee30f4f25e7858e8a7160fd36e803bb2dfe206278659d71a9bcd7a
```