document-database-service/api-ref/source/api_calling/rest_apis.rst

original_name

dds_api_0016.html

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 <dds_api_0016__table18389930> 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 <dds_projectid>.	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 <dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139> 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.