• Cloud Server Backup Service

csbs
  1. Help Center
  2. Cloud Server Backup Service
  3. API Reference
  4. API Usage Guidelines
  5. REST APIs

REST APIs

Public cloud services provide RESTful APIs.

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 RESTful API request or response consists of the following parts:

  • Request URI
  • Request header
  • Request body
  • Response header
  • Response body

Request URI

A request URI is in the following format:

{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. Obtain the value from Regions and Endpoints.

resource-path

Specifies the API access path for performing a specified operation. Obtain the value from the URI of the API, for example, /v1/{project_id}/vpcs/{vpc_id}.

query-string

This parameter is optional. For example, you can set it to the 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 the server to return specified resources.

PUT

Requests the server to update specified resources.

POST

Requests the server to add resources or perform special operations.

DELETE

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

HEAD

Requests a server resource header.

PATCH

Requests the server to update partial content of a specified resource.

If the resource does not exist, the PATCH method creates a resource.

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 header fields

Field

Description

Mandatory

Example

X-Sdk-Date

Specifies the time when the request is sent. The time is in the format of YYYYMMDD'T'HHMMSS'Z'.

The value is the current GMT time of the system.

No

This field is mandatory for AK/SK authentication.

20150907T101459Z

Authorization

Specifies the authentication information.

The value can be obtained from the request signing result.

No

This field is mandatory for AK/SK authentication.

SDK-HMAC-SHA256 Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request, SignedHeaders=content-type;host;x-sdk-date, Signature=55741b6...e1994

Host

Specifies the server domain name and port number of the resources being requested. The value can be obtained from the URL of the service API. The value is in the format of Hostname:Port number. If the port number is not specified, the default port is used. The default port number for HTTPS is 443.

No

This field is mandatory for AK/SK authentication.

code.test.com

or

code.test.com:443

Content-Type

Specifies the request body MIME type. You are advised to use the default value application/json. For APIs used to upload objects or images, the value can vary depending on the flow type.

Yes

application/json

Content-Length

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

No

3495

X-Project-Id

Specifies the project ID. Obtain the project ID by following the instructions in Obtaining a Project ID.

No

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

Specifies the user token.

For details about how to obtain the token, see "Obtaining a User Token" in the Identity and Access Management API Reference. After the request is processed, the value of X-Subject-Token in the header is the token value.

No

This field is mandatory for token authentication.

The following is part of an example token:

MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

(Optional) Request Body

This part is optional. 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 Header

A response header consists of the following two parts:

  • An HTTP status code, from 2xx success code to 4xx or 5xx error code, or a status code that can return the service definition
  • Additional fields, for example Content-Type
    Table 4 lists common response header fields.
    Table 4 Common response header fields

    Field

    Description

    Example

    Content-Length

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

    N/A

    Date

    Specifies the GMT time when a request response is returned.

    Wed, 27 Dec 2016 06:49:46 GMT

    Content-Type

    Specifies the response body MIME type.

    application/json

(Optional) Response Body

This part is optional. 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.

Send a Request

You can initiate a request based on the constructed request message using any of the following:

  • cURL

    cURL is a command-line tool used to perform URL operations and transmit information. It serves as an HTTP client that can send HTTP requests to the server and receive response messages. cURL is applicable to API debugging. For more information about cURL, visit https://curl.haxx.se/.

  • Coding

    You can call APIs using code to assemble, send, and process request messages.

  • REST client

    Both Mozilla Firefox and Google Chrome provide a graphical browser plug-in, that is, REST client, to send and process requests. For Firefox, see Firefox RESTClient. For Google Chrome, see Postman.