Constructing a Request

Constructing a Request

This section describes the structure of a REST API request and uses the IAM API for obtaining a user token as an example to describe how to call an API. The obtained token is used to authenticate the calling of other APIs.

Request Example

POST https://iam-xxx.ctapi.ctyun.cn/v3/auth/tokens?prodInstId=11&startTime=2021-04-04T06:01:46ZHTTP/1.1
Content-Type:application/json
ctyun-eop-request-id:0ffb9b07-d5a8-4e19-b3ce-12dfb9705a1d
Eop-Authorization:4a4bdc57e06542199b5f98d4cd107be2 Headers=ctyun-eop-request-id;eop-date Signature=b2WEo4nh9ewn6SWOP0ii5g8L0z9CT5gprpDWntlCX9I=
Eop-date:20221107T093029Z

{resource-path} Resource path. A standard URI example using codes is as follows:

Before:
/v3/auth/tokens api/code
After:
/v3/auth/tokens%20api/code

Note:

The resource path {resource-path} is the middle of the question mark character (?) from the end of the HTTP Host to the queried string parameter (if any).  Normalize URI paths according to RFC 3986. Remove redundant and relative path components. Each part of the path must be URI encoded.

{query-string} Query parameter. Use the standard query string. Example:

Before:
prodInstId=11&startTime=2021-04-04T06:01:46Z
After:
prodInstId=11&startTime=2021-04-04T06%3A01%3A46Z

Note:

{query-string} is a key-value pair. Assemble it with the equal sign character (=). Values must be URI encoded and must meet the definition requirements of RFC 3986 for URL encoding specifications. URI encoding is not required for keys. Use an empty string for a parameter that has no value.

Appends the ampersand (&) after each parameter value, except for the last value in the list.

Perform percentage encoding for all other characters using %XY, where X and Y are hexadecimal characters (0-9 and capital letters A-F). For example, space characters must be encoded as % 20 (do not use the plus sign (+) as some encoding schemes), and extended UTF-8 characters must be in the format %XY%ZA%BC.

The specific requirements of the RFC 3986 standard are as follows:

The characters A~Z, a~z, 0~9, and the characters like hyphen (-), underline (_), period (.), and equal sign (~) are not encoded.

Encode other ASCII characters. The encoding format is a percent (%) plus a hexadecimal ASCII code. For example, the double quotation mark (") is encoded as %22.

Non-ASCII codes are encoded through UTF-8.

Spaces are encoded as % 20, not a plus sign (+).

Requesting URI

{URI-scheme}://{Endpoint}/{resource-path}? {query-string}

For example:

To obtain the IAM token in a region, you need to use the endpoint (iam-xxx.ctapi.ctyun.cn) of this region, and find the resource-path (/v3/auth/tokens) in the URI for obtaining the user token. Then, assemble the fields by referring to:

https://iam-xxx.ctapi.ctyun.cn/v3/auth/tokens

Note:
To simplify your viewing, the URI part of each API only provides resource-path and the request method. This is because the URI-scheme value of all APIs is HTTPS, and the endpoints in a region are the same. For simplicity, these two parts are omitted.

Request Method

If the resource does not exist, PATCH may create a new resource.

In the URI for obtaining a user token, the request method is POST, and the request is as follows:

POST https://iam-xxx.ctapi.ctyun.cn/v3/auth/tokens

Request Header

Eop-Authorization Signature Authentication Information:

Step I: Constructing a signature string sigture

sigture = combinatorial list of headers that need to be signed + "\n" + encode query + "\n” + toHex (sha256 (original body))

sigture example 1 (Suppose that query is empty and the combinatorial list after Header sorting to be signed is ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160752Z\n**, and the body parameter is converted to hexadecimal e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 after sha256 abstract):
ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160752Z\n\n\n**e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

sigture example 2 (Suppose that query is not empty and the combinatorial list after Header sorting to be signed is ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160752Z\n**, and the body parameter is converted to hexadecimal e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 after sha256 abstract):
ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160930Z\n\n**aa=1&bb=2**\n**e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Step II: Construct a dynamic key kdate

1.         Calculate ktime using eop-date as the data and sk as the key.

2.         Calculate kAk using ak as the data and ktime as the key.

3.         Calculate kdate using the yyyy/mm/dd value of eop-date as data and kAk as the key.

Step III: Constructing a signature

Use kdate as the key and sigture as the data, and perform base64 encode for the result to obtain signature.

Step IV: Constructing Eop-Authorization

1.         Construct Headers.

2.         Obtain Eop-Authorization.

Eop-Authorization:ak Headers=xxx Signature==xxx.