:original_name: dds_api_0016.html .. _dds_api_0016: 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:: **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:: **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. :ref:`Table 3 ` lists common request header fields. .. _dds_api_0016__table18389930: .. table:: **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 :ref:`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** :ref:`Table 4 ` lists common response header fields. .. _dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139: .. table:: **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.