Overview

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:

1. 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.
2. 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

1. Each key pair is comprised of a public key and a private key.
2. Each key pair is assigned with a key ID

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

Key scope

1. Each key pair is assigned with a certain scope of API operations - All APIs by default
2. Each organisation can apply for more than 1 key pair.
3. 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.

Refer to Signature algorithm v1 for Version 1

Refer to Signature algorithm v2 for Version 2