• Data Warehouse Service

dws
  1. Help Center
  2. Data Warehouse Service
  3. API Reference
  4. API Usage
  5. REST API

REST API

The public cloud provides APIs complying with the design principle of RESTful APIs. Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) to dispersed resources so that the resources can be located. Applications on clients use unified resource locators (URLs) to obtain the resources. The URL is in the following format: https://Endpoint/uri. uri indicates the resource path. That is, the API access path.

Public cloud APIs use HTTPS as the transmission protocol. Requests/Responses are transmitted by using JSON packets, with media type represented by Application/json.

DWS provides REST APIs.

In REST, specific information or data on a network is represented by resources. REST allows users to access service resources, such as tags, clusters, and snapshots, by creating, querying, updating, and deleting resources.

The REST API request/response pair consists of the following:

Request URI

A request URI consists of the following:

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

Although the request URI is included in the request header, most languages or frameworks require that it be transferred separately from the request message. Therefore, the request URI is listed independently.

Table 1 Parameters in a URI

Parameter

Description

URI-scheme

Protocol used for transmitting the request. HTTPS is used in DWS APIs.

Endpoint

Domain name or IP address of the server bearing the REST service endpoint. Obtain this value from Regions and Endpoints.

resource-path

Resource path, that is, the API access path. Obtain the value from the URI of a specific API, for example, v3/auth/tokens.

query-string

This parameter is optional, for example, API version or resource selection criteria.

Request Header

A request header contains the following:
  • HTTP methods, which are also called operations or actions, specify the type of operations that you are requesting. Table 2 describes methods supported by DWS REST APIs.
    Table 2 HTTP methods

    Method

    Description

    GET

    Requests a representation of the specified resource.

    PUT

    Requests to update the specified resource.

    POST

    Requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI.

    DELETE

    Requests the server to delete a specific resource such as an object.

    HEAD

    Requests the server resource header.

    PATCH

    Requests to update the partial content of the specified resource.

    If the resource does not exist, the PATCH method may create a resource.

  • (Optional) Additional fields in the request header required by a specified URI and HTTP method. For details about common message headers, see Table 3.
    Table 3 Common request headers

    Parameter

    Description

    Mandatory

    Example Value

    x-sdk-date

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

    The value is the current GMT time of the system.

    No

    This parameter is mandatory for AK/SK authentication.

    20150907T101459Z

    Host

    Indicates the server domain name and port number of the resource being requested. The value can be obtained from the URL of the service API. The value is hostname[:port]. If the port number is not specified, the default port is used. The default port number for https is 443.

    No

    This parameter is mandatory for AK/SK authentication.

    code.test.com

    or

    code.test.com:443

    Content-type

    Indicates the request body MIME type.

    Yes

    application/json

    Content-Length

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

    This parameter is mandatory for POST and PUT requests, but must be left blank for GET requests.

    3495

    X-Project-Id

    Indicates the project ID. This parameter is used to obtain the token for the project.

    No

    e9993fc787d94b6c886cbaa340f9c0f4

    X-Auth-Token

    Indicates the user token. Refer to section Token Authentication to obtain the token.

    Yes

    This parameter is mandatory when token authentication is used.

    -

    X-Language

    Indicates the request language.

    No

    en_us

    NOTE:

    For details about other parameters in the header, see the HTTP protocol documentation.

(Optional) Request Body

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

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, as shown in the API document.
  • Additional fields in the response header required by a specified response, for example, the Content-type response header. For details about common message headers, see Table 4.
    Table 4 Response headers

    Parameter

    Description

    Example Value

    Date

    Indicates a standard HTTP header, which represents the date and time at which the message was originated. The format is defined by RFC 822.

    Mon, 12 Nov 2007 15:55:01 GMT

    Server

    Indicates a standard HTTP header, which includes the software information that the server uses to process the request.

    Apache

    Content-Length

    Indicates a standard HTTP header, which specifies the size of the entity body, in decimal number of bytes, sent to the recipient.

    -

    Content-Type

    Indicates a standard HTTP header, which specifies the media type of the entity body sent to the recipient.

    application/json

(Optional) Response Body

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

Initiating a Request

You can send a request based on the constructed request body using any of the following three methods:

  • cURL

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

  • Code

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

  • REST clients

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