Table Store API

Last Updated: Mar 23, 2018

Applications can use Table Store SDK of Alibaba Cloud to access Table Store. Applications can also use the POST method to send HTTP requests to access Table Store.

This topic introduces the HTTP request structure and data format, and explains how to structure HTTP requests and parse returned results. Developers using Java, Python, C++, Go, Node.JS, and C# can use the official SDKs. If you use another language to access Table Store, use HTTP messages to interact with Table Store based on either the content in this topic, or through an independently compiled SDK.

Current API version

API Version: 2015-12-31

HTTP messages

Table Store accepts HTTP requests from applications, processes the requests according to the relevant logic, and uses HTTP messages to return results data after processing. Data in the HTTP requests and responses are organized using ProtocolBuffer protocol format. For more information on the ProtocolBuffer protocol, see Table Store ProtocolBuffer Message Definitions. The following parts introduce the specific formats of the HTTP request headers and bodies, and responses.Table Store accepts HTTP requests from applications, processes the requests according to the relevant logic, and uses HTTP messages to return the resulting data after processing. Data in the HTTP requests and responses are organized using the ProtocolBuffer protocol format. For more information on the ProtocolBuffer protocol, see Table Store ProtocolBuffer message definitions. The following introduces the specific formats of the HTTP request headers and bodies, and responses.

HTTP request

HTTP request URL

The URLs used to access Table Store are structured as follows.

  1. Internet access URL:https://<instance>.<region>.ots.aliyuncs.com/<operation>
  2. Intranet access URL:https://<instance>.<region>.ots-internal.aliyuncs.com/<operation>

Parameters in the URL are described as follows.

Parameter Description Case sensitive
instance The instance name. Instances are created by users. The information for cloud account instances can be viewed on the Table Store console. No
region The Alibaba Cloud service node. Table Store is deployed across different Alibaba Cloud service nodes located in multiple regions. When creating an instance, you must specify an Alibaba Cloud region. In the Table Store console, you can view the Alibaba Cloud region where the instance belongs. No
operation The Table Store operation name. All Table Store operations are listed in API Reference. Yes

The following URL is the destination URL for a ListTable request targeting an instance named myInstance in the China East 1 (Hangzhou) region.

http://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable

HTTP Request Header

Table Store requires that the HTTP request headers contain the following information:

  • x-ots-date: The request issue time. This uses the UTC time format. Format: %Y-%m-%dT%H:%M:%S.000Z

  • x-ots-apiversion: The API version number. Version numbers are date strings. This document uses the API version number 2015-12-31.

  • x-ots-accesskeyid: Your unmarkTextString’s AccessKeyID.

  • x-ots-instancename: The instance name.

  • x-ots-contentmd5: The MD5 for the HTTP body, encoded by base64.

  • x-ots-ststoken: If STS token is used, you must specify the header having the value of token.

  • User-Agent: The user agent. The identifier is user-defined. Recommended format: aliyun-tablestore-sdk-{Language}/Version(operating system name/operating system version/computer type;language version)

  • x-ots-signature: The request signature. The signature calculation method is as follows.

    1. Signature = base64(HmacSha1(AccessKeySecret, StringToSign));
    2. StringToSign = CanonicalURI + '\n' + HTTPRequestMethod + '\n\n' + CanonicalHeaders
    3. CanonicalHeaders = LowerCase (HeaderName1) + ':' + Trim(HeaderValue1) + '\n' + ... + LowerCase (HeaderNameN) + ':' + Trim(HeaderValueN) + '\n'

    The functions used in the preceding pseudocode are described as follows.

    Function Description
    HmacSha1 Hmac-Sha1 encryption algorithm. During Table Store request signature calculation, use StringToSign as the message and AccessKeySecret as the secret key.
    base64 Base64 encoding algorithm.
    LowerCase Convert all letters in the string to lowercase.
    Trim Remove spaces at the front and end of the string.
  • CanonicalURI: The path section in the HTTP URL is given in the following example, with the CanonicalURI set as /ListTable.

    http://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable

  • HTTPRequestMethod: HTTP request methods (such as GET, POST, or PUT). The Table Store HTTP API only supports POST.

    Note: POST must be written in uppercase.

  • CanonicalHeaders: CanonicalHeaders are Table Store HTTP header strings (not including the x-ots-signature header) structured according to the following rules:

    • It must only contain the Table Store standard headers that begin with x-ots-.

    • All header item names must be in lowercase and the values must use the Trim operation to remove any spaces.

    • The header items are ordered by name in ascending lexicographic order.

    • The names and values of the header items must be separated by :.

    • A newline character must be used to separate headers.

Table Store verifies the following HTTP requests:

  • The consistency of the x-ots-contentmd5 header value with the MD5 calculated for the data contained in the HTTP body.

  • The signature in the request header is correct.

  • The time in x-ots-date differs by less than 15 minutes from the time of the server (earlier or later).

If the verification request fails, Table Store returns an authentication error.

HTTP Request Body

Table Store requires that the HTTP request body is a string serialized by the ProtocolBuffer message defined by Table Store. The body length must be less than 2 MB.

For Table Store requests’ ProtocolBuffer message definitions, see Table Store ProtocolBuffer message definitions.

HTTP Response

HTTP Response Header

Table Store returns the HTTP response with the following headers items:

  • x-ots-date: The request issue time. The date uses UTC time. Format: %Y-%m-%dT%H:%M:%S.000Z. For example, 2017-09-21 16:05:52, Beijing time, x-ots-date is 2017-09-21T08:05:52.000Z.

  • x-ots-requestid: The request ID of this request.

  • x-ots-contenttype: The response content type. Fixed as protocol buffer string.

  • x-ots-contentmd5: An MD5 value calculated based on the response content and encoded by base64.

  • Authorization: The response signature. The response contains a signature only if the request signature has passed the Table Store verification. The signature calculation method is as follows.

    1. Authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1(AccessKeySecret, stringToSign))
    2. StringToSign = CanonicalHeaders + CanonicalURI
    3. CanonicalHeaders = LowerCase (HeaderName1) + ':' + Trim(HeaderValue1) + '\n' + ... + LowerCase (HeaderNameN) + ':' + Trim(HeaderValueN) + '\n'

    Descriptions of the functions used in the preceding pseudocode are the same as those used in HTTP Request Header.

  • CanonicalURI: The path section in the HTTP URL is given in the following example, with the CanonicalURI set as /ListTable.

    http://myInstance.cn-hangzhou.ots.aliyuncs.com/ListTable

  • CanonicalHeaders: The Table Store HTTP header strings (not including the x-ots-signature header) structured according to the following rules:

    • It must only contain the Table Store standard headers that begin with x-ots-.

    • All the header item names must be in lowercase and the values must use the Trim operation to remove any spaces.

    • The header items are ordered by name in the ascending lexicographic order.

    • The names and values of the header items must be separated by :.

    • A newline character must be used to separate headers.

The client must verify the Table Store response as follows:

  • Verify that the signature in the response header is correct.

  • Verify that the time in x-ots-date differs by less than 15 minutes from the time of the client (earlier or later).

  • Verify the consistency of the x-ots-contentmd5 header value with the MD5 calculated for the response data.

If the verification response fails, you must reject the response data in code, because this response may not come from the Table Store service.

HTTP Response Content

Table Store requires that the HTTP response content is a string that has been serialized by the ProtocolBuffer message defined by Table Store. The Body length cannot exceed 2 MB. Each Table Store request message corresponds to one Table Store response message. After the application deserializes the response content, it can read the Table Store operation results.

Signature examples

Two request and response signature verification examples are provided as follows. After implementing a signature algorithm, use the following examples to test if the algorithm was implemented correctly.

Request signature examples

Assume that your AccessKeyID is LTAIhGbDGGOYJDZt and the AccessKeySecret is DomcqbBGOyYNWue3DlVArEUBeSlpE.

  1. POST /ListTable HTTP/1.0
  2. x-ots-date: 2017-09-21T08:32:07.000Z
  3. x-ots-apiversion:2015-12-31
  4. x-ots-accesskeyid: LTAIhGbDGGOYJDZt
  5. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  6. x-ots-instancename: first

Thus, your request signature result is as follows.

  1. stringToSign = '/ListTable\nPOST\n\nx-ots-accesskeyid:LTAIhGbDGGOYJDZt\nx-ots-apiversion:2015-12-31\nx-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-date:2017-09-21T08:32:07.000Z\nx-ots-instancename:first\n'
  2. signature = base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  3. = FjtBHd8FeB021PwTQI+XI/VMM24=

Response signature examples

Assume that your AccessKeyID is LTAIhGbDGGOYJDZt and the AccessKeySecret is DomcqbBGOyYNWue3DlVArEUBeSlpE.

  1. /ListTable
  2. x-ots-contentmd5: 1B2M2Y8AsgTpgAmY7PhCfg==
  3. x-ots-requestid: 000559ae-ed86-f416-0d88-990a09ec9ed2
  4. x-ots-contenttype: protocol buffer
  5. x-ots-date:2017-09-21T08:32:07.815799Z

Thus, the Table Store response signature result is as follows.

  1. stringToSign = 'x-ots-contentmd5:1B2M2Y8AsgTpgAmY7PhCfg==\nx-ots-contenttype:protocol buffer\nx-ots-date:2017-09-21T08:32:07.815799Z\nx-ots-requestid:000559ae-ed86-f416-0d88-990a09ec9ed2\n/ListTable'
  2. authorization = 'OTS ' + AccessKeyID + ':' + base64(HmacSha1('DomcqbBGOyYNWue3DlVArEUBeSlpE', stringToSign))
  3. = 'OTS LTAIhGbDGGOYJDZt:LTktOlJYRenAGIpMn41zIab0ut0='
Thank you! We've received your feedback.