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.
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.
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.
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.