Cube API follows HTTP/1.1 REST specification and adopts RSA signature as authentication to enhance security.

API Service Specification

SLA

99%

Accumulated less than 4 hours maintenance window monthly

Throughput

RPS = 2500

Average Response Time

5s (excluding network latency to and from caller)

p99 < 4s

API Usage

Rate Limiting

Maximum query per second (QPS) per IP: 10

Maximum concurrent connections: 3

Request exceeding above limit may receive response status code 429

Quota

Maximum queries per day per IP: 5,000

Basic Settings

Production Base URL

baseUrl = "https://api.linksfield.net/cube/v4"

Global Header*

Parameter	Example	Mandatory	Description
Accept-Language	zh-CH	No	Default: en-US
Content-Type	application/json	No	application/json
Authorization	LF {keyId}/{sign}	Yes	Each pair of public and private keys corresponds to a keyId
X-LF-Api-Version* (note 1)	1.0	No	Default: the latest-1 version
X-LF-Signature-Type* (note 2)	1.0	No	Default: 1.0/ 2.0

API retirement mechanism:

API Version

At most two versions will be maintained at the same time for an API, for example v1.0 and v2.0.

When X-LF-Api-Version is not specified in the header, the earlier version, say v1.0 will be selected.

When there is a new API version say v2.0 released for an API, v1.0 will be labeled as deprecated. Deprecated version will be retired after 12 months' time. You may choose to upgrade the API at any point of time before that happens.

Important Notice about X-LF-Signature-Type:
Global Header has a different structure in Signature Version 2, please refer to Sign V2 document for details.

Time and Timezone

Time in parameters should follow:
timestamp format (in ms) and the timezone is UTC0 by default.

Batch

Some APIs return batch data in response, there are two ways to request:

When data is stored in database
page_size and page_no

When data is stored in big data store
page_size and last_cursor

In either case, the maximum (default) returned data count in one request is: 100

Status Code

Http Status Code	Description	Remarks
200	Success	-
400	Invalid parameter	Parameter bad format or missing
401	Unauthorised	Authorization is missing
403	Invalid signature	Signature verification fails
429	Rate Limiting	Exceeds rate limit
500	Service Error	-

Authentication

Please apply for enterprise key pair from FAE/ Project Manager

Key

Key	Key Length	Description
RSA	1024 bit	Private key to sign; Public key to verify signature.

Key pair

Each key pair is comprised of a public key and a private key.

Each key pair is assigned with a key ID

    keyPair: {
        keyId: String,
        publicKey: String,
        privateKey: String, 
    }

Key scope

Each key pair is assigned with a certain scope of API operations - All APIs by default

Each organisation can apply for more than 1 key pair.

Organisation's key can NOT be used to access resources of its sub-organisations.

Token - Signature

Signature of the request should be included in token, in the header Authorization

-H Authorization: LF {KeyID}/{Signature}

//Example:
Authorization: LF b30a5e0e135d42e6ab43b021a30b7987/XbEd2v1LxXpGzzu8RZHwmRKmowVCGtuCdpWWgTB1DgWqy19mAGfNx4TvrmBpDqDyzPnxE2+WZAEE9wjpnR6pWziGfT+VL6uAYyPKWnFbAsrmS0Uas7fMickMF6i59sWxmYhVhLbrb4ZF2/fKoaLcdP1ynvhXqibAROiEvTl/kAc=

Signature	Algorithm
Sign the API contents	sha1withRSA

An incorrect token will receive http response code 401 Unauthorized / 403 Forbidden

The Signature calculation algorithm is `SHA1withRSA` but there are two versions of method implemented, in terms of constructing the data for signature calculation.

Overview

API Service Specification

SLA

Throughput

Average Response Time

API Usage

Rate Limiting

Quota

Basic Settings

Production Base URL

Global Header*

Time and Timezone

Batch

Status Code

Authentication

Key

Key pair

Key scope

Token - Signature

The Signature calculation algorithm is `SHA1withRSA` but there are two versions of method implemented, in terms of constructing the data for signature calculation.

Refer to Signature algorithm v1 for Version 1

Refer to Signature algorithm v2 for Version 2

Overview

API Service Specification#

SLA#

Throughput#

Average Response Time#

API Usage#

Rate Limiting#

Quota#

Basic Settings#

Production Base URL#

Global Header*#

Time and Timezone#

Batch#

Status Code#

Authentication#

Key#

Key pair#

Key scope#

Token - Signature#

The Signature calculation algorithm is SHA1withRSA but there are two versions of method implemented, in terms of constructing the data for signature calculation.#

Refer to Signature algorithm v1 for Version 1#

Refer to Signature algorithm v2 for Version 2#

API Service Specification

SLA

Throughput

Average Response Time

API Usage

Rate Limiting

Quota

Basic Settings

Production Base URL

Global Header*

Time and Timezone

Batch

Status Code

Authentication

Key

Key pair

Key scope

Token - Signature

The Signature calculation algorithm is `SHA1withRSA` but there are two versions of method implemented, in terms of constructing the data for signature calculation.

Refer to Signature algorithm v1 for Version 1

Refer to Signature algorithm v2 for Version 2