• Data Ingestion Service

dis
  1. Help Center
  2. Data Ingestion Service
  3. API Reference
  4. API Usage
  5. REST API Overview

REST API Overview

DIS provides REST APIs.

In REST, specific information or data on a network is represented by a resource, which is referenced with a uniform resource identifier (URI). Clients on a network can locate resources using uniform resource locators (URLs).

The format of a URL is as follows: https://Endpoint/uri

Table 1 describes URL parameters.

Table 1 Parameter description

Parameter

Description

Endpoint

Name of the server that provides the requested resource. For more information about regions and endpoints, see Regions and Endpoints.

uri

Path in which the requested resource is located. You can obtain the path from the URI of a specific API.

A REST API request or response consists of the following five parts:

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

Request URL

The format of a request URL is as follows;

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

Table 2 Parameter description

Parameter

Description

URL-scheme

Specifies the protocol used to transfer requests. The DIS API must use HTTPS.

Endpoint

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

resource-path

Specifies the resource path, that is, the API access path. You can obtain the path from the URI of a specific API.

query-string

(Optional) For example, API version or resource selection criteria.

Request Header

A request header consists of an HTTP method and additional field in the request header.

  • HTTP method, also known as an operation or action, used to specify how to access a specific resource.

    Table 3 describes the HTTP methods supported by the REST API of DIS.

    Table 3 HTTP methods

    Method

    Description

    GET

    Requests the server to return a specific resource.

    POST

    Requests the server to add a resource or perform special operations.

    PUT

    Requests the server to update a specific resource.

    DELETE

    Requests the server to delete a specific resource, for example, to delete an object.

    HEAD

    Requests the server to obtain the resource header.

    PATCH

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

    If the resource does not exist, a resource can be created using the PATCH method.

  • (Optional) Additional field in the request header required by a specific URI and HTTP method

    For details about common request headers, see Table 4. For details about the request authentication information, see Authenticating API Requests.

    Table 4 Common request message headers

    Header

    Mandatory

    Type

    Description

    Content-Type

    Yes

    String

    Type of the resource content. For example: application/json

    Default value: none

    X-Sdk-Date

    Yes

    String

    Time to send a request. The time format is YYYYMMDD'T'HHMMSS'Z'. For example: 20180820T101459Z

    Default value: none

    Authorization

    Yes

    String

    Authorization information in a request.

    SDK-HMAC-SHA256 Credential=ZIRRKMTWPTQFQI1WKNKB/20150907/eu-de/ec2/sdk_request, SignedHeaders=content-type;host;x-sdk-date, Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994

    Default value: none

    Host

    Yes

    String

    Requested service information.

    Default value: none

Request Body

A request body is encapsulated and sent in the JSON format, and is used to transfer content other than the request header. The format is specified by Content-Type in the request header.

Which fields are mandatory and optional in an HTTP request varies with different URI objects.

Response Header

A response header consists of an HTTP status code and additional field in the response header:

  • HTTP status code. For details, see Status Codes.
  • Additional field in the response header required by a specific response, for example, the Content-Type response header.

    For details about common response headers, see Table 5.

    Table 5 Common response message headers

    Header

    Type

    Description

    Content-Type

    String

    Type of the resource content. For example: application/json

    Default value: none

    Date

    String

    DIS system response time. For example: Mon, 15 Jul 2013 21:08:05 GMT

    Default value: none

Response Body

The response body is encapsulated as JSON-formatted text, and is used to transfer content other than the response header. The format is specified by Content-Type in the response header.

Initiating a Request

There are three methods to initiate a request to the server end:

  • cURL

    cURL is a command-line tool used to perform URL operations and transmit information. It can serve as an HTTP client to send HTTP requests to the server end and receive response messages. cURL is suitable for use in API tuning scenarios. For more information about cURL, visit https://curl.haxx.se/.

  • Code

    You can call an API through code to assemble, send, and process requests.

  • REST client

    Mozilla Firefox and Google Chrome provide a graphical browser plug-in for REST clients to send and process requests.

    For Mozilla Firefox, see Firefox REST Client.

    For Google Chrome, see Postman Interceptor.