REST APIs

API requests sent by third-party applications to public cloud services must be authenticated using signatures.

Public cloud APIs follow RESTful API design rules.

In REST, specific information or data on a network is represented by resources. REST allows users to access service resources by creating, querying, updating, and deleting resources.

A REST API request and response are divided into the following parts:

  • Request URI

  • Request header

  • Request body

  • Response header

  • Response body

Request URI

A request URI consists of the following:

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

Although a request URI is included in a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.

Table 1 URI parameter description

Parameter

Description

URI-scheme

Specifies the protocol used for transmitting requests.

Endpoint

Specifies the domain name or IP address of the server bearing the REST service endpoint.

To obtain the parameter value, see Regions and Endpoints.

resource-path

Specifies the API access path for performing a specified operation. Obtain this value from the URI of the API, for example, v3/auth/tokens.

query-string

This parameter is optional. For example, you can set it to API version or resource selection criteria.

Request Methods

HTTP methods, which are also called operations or actions, specify the type of operations that you are requesting.

Table 2 HTTP methods

Method

Description

GET

Requests a server to return the specified resources.

POST

Requests a server to add resources or perform special operations.

DELETE

Requests a server to delete specified resources, for example, an object.

Request Header

You can also add additional fields to the request header, for example, the fields required by a specified URI and an HTTP method. Table 3 lists common request header fields.

Table 3 Common request headers

Name

Description

Mandatory

Example

Content-Type

Specifies the MIME type of the request body.

Yes

application/json

Content-Length

Specifies the length of the request body. The unit is byte.

This parameter is optional for POST requests, but must be left blank for GET requests.

3495

X-Project-Id

Specifies the project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

No

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

Specifies the user token.

Yes

-

(Optional) Request Body

A request body is generally sent in a structured format (for example, JSON or XML), corresponding to Content-Type in the request header, and is used to transfer content other than the request header.

If the request body contains full-width characters, convert the full-width characters into the UTF-8 encoding format.

Response Headers

A response header consists of the following two parts:

  • An HTTP status code, which is a service-defined status code indicating a success or an error

  • Additional fields, for example Content-Type

    Table 4 lists common response header fields.

    Table 4 Common response headers

    Name

    Description

    Example

    Date

    Standard HTTP header field, which represents the date and time at which the message was originated. The format is defined by RFC 822.

    Wed, 27 Dec 2018 06:49:46 GMT

    Content-Length

    Standard HTTP header field, which specifies the size of the entity body, in decimal number of bytes, sent to the recipient.

    -

    Content-Type

    Standard HTTP header field, which specifies the media type of the entity body sent to the recipient.

    application/json

(Optional) Response Body

A response body is generally returned in a structured format (for example, JSON or XML), corresponding to Content-Type in the response header, and is used to transfer content other than the response header.