• MapReduce Service

mrs
  1. Help Center
  2. MapReduce Service
  3. API Reference
  4. API Use Methods
  5. REST APIs

REST APIs

MRS provides the Representational State Transfer (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 REST API request or response consists of the following five parts:

Request URI

A 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 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. HTTPS must be used in MRS APIs.

Endpoint

Specifies the domain name or IP address of the server that carries the REST service endpoint, which can be obtained from Regions and Endpoints.

resource-path

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

Query string

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

PUT

Requests a server to update the specified resources.

POST

Requests a server to add resources or perform special operations.

DELETE

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

HEAD

Requests a server resource header.

PATCH

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

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

Request Header

A request header consists of several header fields. Each header field consists of a field name, a colon (:), and a field value.

You can also add additional fields to the request header, for example, the fields required by a specified URI and an HTTP 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

Parameter

Description

Mandatory or Not

Example

X-Sdk-Date

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.

This parameter is mandatory for AK/SK authentication.

20150907T101459Z

Authorization

Signature authentication information

The value can be obtained from the request signing result.

For details, see Request Signing Procedure.

This parameter is mandatory for AK/SK authentication.

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

Host

Requested server information, which 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.

This parameter is mandatory for AK/SK authentication.

code.test.com

or

code.test.com:443

Content-type

MIME type of the sent request body

Yes

application/json

Content-Length

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

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

No

e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

User token

No

This parameter is mandatory for token authentication.

-

X-Language

Request language. Values include:

  • zh-cn: Chinese
  • en-us: English

No

en-us

NOTE:

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

Request Body

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.

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 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 response headers, see Table 4.
    Table 4 Common response headers

    Parameter

    Description

    Example

    Date

    Standard HTTP header, which specifies the date and time at which the message was sent. The format is defined by RFC 822.

    Mon, 12 Nov 2007 15:55:01 GMT

    Server

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

    Apache

    Content-Length

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

    xxx

    Content-type

    Standard HTTP header, which specifies the media type of the entity body sent to the recipient.

    application/json

Response Body

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.

Sending 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 an HTTP client that can send HTTP requests to the server and receive response messages. It is applicable to API debugging. For more information about cURL, visit https://curl.haxx.se/.

  • Code

    You can call 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 Mozilla Firefox, see Firefox REST Client. For Google Chrome, see Postman Interceptor.