Help Center > > API Reference> Calling APIs> Making an API Request

Making an API Request

Updated at: Aug 13, 2019 19:34

CCE provides 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 of APIs described in Cluster Management is in the format of https://Endpoint/uri. In the URL, uri indicates the resource path, that is, the API access path.
  • The URL of Kubernetes-native APIs described in Storage Management is in the format of https://{clusterid}.Endpoint/uri. In the URL, {clusterid} indicates a cluster ID, and uri indicates the resource path, that is, the API access path.
Table 1 Parameter description of a URL

Parameter

Description

{clusterid}

Cluster ID. After a cluster is created, the API provided in Listing Clusters in a Specified Project is called to obtain the cluster ID.

Endpoint

URL that is the entry point for a web service. It is obtained from Regions and Endpoints.

uri

Resource path, that is, the API access path. You can obtain the value of this parameter from the URI of the specific API, for example, v3/auth/tokens.

A pair of REST API request/response contains the following parts:

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

Request URI

The request URI consists of the following parts:

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

Although the request URI is included in the request header, most programming languages or frameworks require you to transfer it separately from the request message.

Table 2 URI parameter description

Parameter

Description

URI-scheme

Specifies the protocol used to transmit the request. HTTPS is used for transmitting API requests.

Endpoint

Specifies the domain name or IP address of the server that carries the REST service endpoint. You can obtain the value of this parameter from Regions and Endpoints.

resource-path

Specifies the API access path for performing a specified operation. You can obtain the value of this parameter from the URI of the specific API, for example, v3/auth/tokens.

Query string

Provides optional additional parameters, such as the API version or resource selection criteria.

Request Method

HTTP method, which tells the service what type of operation is being requested.
Table 3 HTTP methods

Method

Description

GET

Requests the server to provide the specified resource.

PUT

Requests the server to update the specified resource.

POST

Requests the server to add a new resource or perform the specified operation.

DELETE

Requests the server to delete the specified resource.

HEAD

Similar to the GET method, the HEAD method requests the server to provide the specified resource, but the server returns only the response header (excluding the response body) to this request.

PATCH

Requests the server to update a resource or create a new resource if the target resource does not exist.

Request Header

Optional additional header fields, such as the fields required by specified URIs and HTTP methods. For details about common request message header fields, see Table 4; for details about request authentication information, see Authentication.
Table 4 Common request headers

Name

Description

Mandatory

Example

X-Auth-Token

User token.

Mandatory for token authentication.

-

Content-Type

Type (or format) of the message body.

Yes

application/json;charset=utf-8 or application/json

X-Sdk-Date

Time at which the request was sent.

The format is YYYYMMDD'T'HHMMSS'Z. The value is the Greenwich Mean Time (GMT) of the system.

Mandatory for AK/SK authentication.

-

Authorization

Authentication information, which can be obtained from the request signing result.

Mandatory for AK/SK authentication.

-

Host

Information about the requested server. 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 HTTPS port 443 is used.

Mandatory for AK/SK authentication.

-

(Optional) Request Body

A request body conveys information other than the request header and is generally sent in a structured format (for example, JSON or XML) defined by the request header field Content-type.

Response Header

A response header contains the following two parts:

  • An HTTP status code, ranging from 2xx (success codes) to 4xx or 5xx (error codes). Alternatively, a service-defined status code may be returned, as described in the API reference.
  • Optional additional header fields to support the request's response, such as a Content-type response header. Table 5 lists the details about standard response headers.
    Table 5 Standard HTTP response headers

    Name

    Description

    Example

    Date

    A standard HTTP header, which specifies the date and time when the response was sent. The format of the date and time is defined in RFC 822.

    Mon, 12 Nov 2007 15:55:01 GMT

    Server

    A standard HTTP header, which contains the information about the software that the server uses to process requests.

    Apache

    Content-Length

    A standard HTTP header, which indicates the size of the response body, in decimal number of bytes.

    xxx

    Content-Type

    A standard HTTP header, which specifies the media type of the response body sent to the recipient.

    application/json

(Optional) Response Body

A response body conveys information other than the response header and is generally sent in a structured format (for example, JSON or XML) defined by the response header field Content-type.

Initiating Requests

There are three methods to initiate requests to the server:

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

    Mozilla Firefox and Google provide a graphical browser plug-in for REST clients to send and process requests. For details, see Firefox REST Client and Google Postman.

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?







Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel