• Cloud Search Service

css
  1. Help Center
  2. Cloud Search Service
  3. API Reference
  4. API Calling

API Calling

Public cloud services provide 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.

REST APIs

CSS provides REST 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 five parts:

  • 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 transmitted separately from the request message. Therefore, the request URI is listed independently.

    Table 1 Parameters in a URI

    Parameter

    Description

    URI-scheme

    Specifies the protocol used for transmitting requests.

    Endpoint

    Name of the server used by the request, which is obtained from Regions and Endpoints.

    resource-path

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

    Query string

    This parameter is optional. You can set it to the API version or resource selection criteria.

  • Request method
    HTTPS methods, which are also called operations or actions, specify the type of operations that you are requesting.
    Table 2 HTTPS methods

    Method

    Description

    GET

    Requests the server to return the specified resource.

    PUT

    Requests the server to update the specified resource.

    POST

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

    DELETE

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

    HEAD

    Requests the server resource header.

    PATCH

    Requests the server to apply partial modifications to a resource.

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

  • Request header
    The request header is optional and refers to the additional request field, for example a field required by a specific URI or HTTPS method. For details about common request headers, see Table 3. For details about the request authentication information, see Obtaining Request Authentication Information.
    Table 3 Common request headers

    Name

    Description

    Mandatory

    Examples

    Content-Type

    Message body type (format).

    Yes

    application/json

    X-Auth-Token

    Token authentication information. For details about how to obtain token authentication information, see Token Authentication.

    This field is mandatory when token authentication is used.

    -

    X-Sdk-Date

    Time when a request was sent.

    This field is mandatory when AK/SK authentication is used.

    20151222T034042Z

    Authorization

    Signature authentication information, which comes from the request signature result.

    This field is mandatory when AK/SK authentication is used.

    SDK-HMACSHA256

    Credential=ZIRRKMTWPTQFQI1WKNKB/20151222/cnnorth-1/ec2/sdk_request,

    SignedHeaders=connection;contenttype;host;x-sdk-date,

    Signature=7972cc9145876d174b3862188a0f61819431fa71c8a8a060809ea8b898e3eaa9

  • Request body

    A request body is generally sent in a structured format (for example, JSON or XML). It corresponds 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 HTTPS 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 specific response, for example, the Content-Type response header. For details about common response headers, see Table 4.
      Table 4 Response header

      Name

      Description

      Examples

      Date

      Standard HTTPS 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

      Standard HTTPS header, which includes the software information that the server uses to process the request.

      Apache

      Content-Length

      Standard HTTPS header, which specifies the size of the entity body, in decimal number of bytes, sent to the recipient.

      -

      Content-Type

      Standard HTTPS header, Specifies the media type of the entity body sent to the recipient.

      application/json

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

You can initiate a request based on constructed request messages using any of the following three methods:

  • cURL

    cURL is a command-line tool used to perform URL operations and transmit information. It can serve as an HTTPS client to send HTTPS 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 invoke APIs using code to assemble, send, and process request messages.

  • REST client

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