# 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 Chinese characters, convert the Chinese 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.

Parent topic: API Calling