This section describes the structure of a REST API request, and uses "Querying User Resources Based on regionID" of ECS as an example to demonstrate how to call the API.

Sample Request

POST https://ctecs-xxx.ctapi.ctyun.cn//v4/region/customerResources?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. Example of an encoded standard URI:

Front:

/v4/region/customerResources api/code

Back:

/v4/region/customerResources%20api/code

Note:

Resource path {resource-path} is between the end of HTTP Host and the question mark (?) of the query string parameter (if any). The redundant and relative path parts need to be removed according to the RFC 3986 standardized URI path specifications. Each part of the path must be URI encoded.

{query-string} Query parameter. Example of a standard query string:

Front:

prodInstId=11&startTime=2021-04-04T06:01:46Z

Back:

prodInstId=11&startTime=2021-04-04T06%3A01%3A46Z

Note:

{query-string} is a key-value pair that spliced with an equal sign (=). The value must be URI encoded based on the RFC 3986 URL encoding specifications, not for the key. Use an empty string for parameters without a value.

Append an ampersand (&) to every parameter value, except for the last one in the list.

Use %XY to perform percent encoding on all other characters. X and Y indicate hexadecimal characters (0–9 and A–F). For example, the space character must be encoded as %20 (instead of a + used in some encodings), and an extended UTF-8 character must be encoded in the "%XY%ZA%BC" format.

RFC 3986 requirements:

Character A-Z, a-z, 0-9, and special characters including -, _, . are not encoded.

Encode all other ASCII code characters. The encoding format is % plus a hexadecimal ASCII code. For example, double quotes (") are encoded as %22.

Non-ASCII code is encoded in UTF-8 format.

The space is encoded as %20, instead of a plus sign (+).

The requested URI.

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

Parameter	Description
URI-scheme	Protocol used to transmit requests. All current APIs use HTTPS.
Endpoint	Domain name or IP address of the server bearing the REST service. The endpoint varies between services in different regions. It can be obtained from regions and endpoints. For example, the endpoint of ECS in a specific region is "ctecs-xxx.ctapi.ctyun.cn".
resource-path	Access path of an API for performing a specific operation. Obtain the path from the URI of an API. For example, the resource-path of the API used to query user resources based on regionID is "/v4/region/customerResources".
query-string	Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of Parameter name=Parameter value. For example, ? limit=10 indicates that a maximum of 10 data records will be displayed.

Example:

To query user resources based on regionID, obtain the endpoint "ctecs-xxx.ctapi.ctyun.cn" for this region and the resource-path (/v4/region/customerResources) in the URI of the API. Then, construct the URI as follows:

https://ctecs-xxx.ctapi.ctyun.cn/v4/region/customerResources

Note:

To simplify the URI display, each API is provided only with a resource-path and a request method. This is because the URI-scheme of all APIs is HTTPS, and the endpoints of all APIs in the same region are identical.

Request Methods

Method	Description
GET	Request the server to return specific resources.
PUT	Request the server to update specific resources.
POST	Request the server to add resources or perform special operations.
DELETE	Request the server to delete specific resources, for example, an object.
HEAD	Requests the server to return the header.
PATCH	Requests the server to update partial content of a specific resource.

If the resource does not exist, a new resource may be created by PATCH.

For example, in the case of the API used to obtain a user token, the request method is POST. The request is as follows:

POST https://ctecs-xxx.ctapi.ctyun.cn/v4/region/customerResources

Request Header

Name	Description	Required or not	Example
Content-Type	Message body type.	Yes	application/json
ctyun-eop-request-id	Request ID.	Yes	0ffb9b07-d5a8-4e19-b3ce-12dfb9705a1d
Eop-Authorization	Signature authentication.	Yes	4a4bdc57e06542199b5f98d4cd107be2 Headers=ctyun-eop-request-id;eop-date Signature=b2WEo4nh9ewn6SWOP0ii5g8L0z9CT5gprpDWntlCX9I=
Eop-date	Time. Valid period: 15 minutes.	Yes	20221107T093029Z

Eop-Authorization

Eop-Authorization Signature authentication:

Step 1: Construct a string for signature (sigture)

sigture = combined list of ranked headers that need to be signed + "\n" + encoded query + "\n" + toHex(sha256 (original body)).

Name	Description
Combined list of ranked Headers that need to be signed	Splice ctyun-eop-request-id and eop-date in the header_name:header_value format, use \n as the ending character of each header, and sort header_name alphabetically. Note: ctyun-eop-request-id and eop-date must be signed as required by EOP. The signatures of other parameters are optional. Example (Amid the background when you need to sign ctyun-eop-request-id, eop-date, and host): ctyun-eop-request-id:123456789\neop-date:20210531T100101Z\n.
Encoded query	The query is spliced with ampersands (&). The key and value are connected with an equal sign (=), and the value must be encoded. All query parameters must be signed.
toHex(sha256(original body))	The inbound body parameter is sha256 digested, and the digested result is converted to hexadecimal.

sigture example 1: (Predefinition: The query is empty, sorted headers to be signed are as follows: ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160752Z\n**, and the sha256 digested body parameter in hexadecimal is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855): ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160752Z\n\n\n **e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

sigture example 2: (Predefinition: The query is not empty, sorted headers to be signed are as follows: ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680** \neop-date:20220525T160752Z\n**, and the sha256 digested body parameter in hexadecimal is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855): ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680**\neop-date:20220525T160930Z\n\n**aa=1&bb=2**\n**e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Step 2: Construct the dynamic key (kdate)

Use eop-date as the data and sk as the key to calculate ktime.
Use ak as the data and ktime as the key to calculate kAk.
Use the kAk as the key and the year, month, and day for the eop-date as the data to calculate kdate.

Name	Description
eop-date	yyyymmddTHHMMSSZ (20211221T163614Z) (year, month, day, T hour, minute, second Z).
Ktime	Use eop-date as the data and sk as the key to calculate ktime. Ktime = hmacSha256(eop-date,sk)
kAk	Use ak as the data and ktime as the key to calculate kAk. kAk = hmacsha256(ak,ktime)
kdate	Use the kAk as the key and theyear, month, and dayfor the eop-date as the data to calculate kdate.

Step 3: Construct the signature

Use kadate as the key, sigture as the data, and encode the result in Base64 to get the signature.

Name	Description
Signature	hmacsha256(sigture ,kdate). Encode the result above in Base64 to get the Signature .

Step 4: Construct Eop-Authorization

Construct headers.
Obtain Eop-Authorization.

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

Name	Description
Headers	Splice target headers alphabetically in the header_name format, separated with commas (,). Example (Amid the background when you need to sign ctyun-eop-request-id and eop-date): Headers=ctyun-eop-request-id;eop-date.
Eop-Authorization	Eop-Authorization:ak Headers=xxx Signature=xxx. Note: Separate the ak, Headers, and Signature with space. Example: Eop-Authorization:ak Headers=ctyun-eop-request-id;eop-date Signature=NlMHOhk5bVfZ9MwDSSJydcZjjENmDtpNYigJGVb. Note: If the headers to be signed are more than the default ctyun-eop-request-id and eop-date, add the parameters to request header (http_client) and Eop-Authorization.

Cloud Server Backup Service

Construct a Request