3 How to call

This page describes how to call Mercury Cloud OpenAPI.

3.1 Base URL

The base service endpoint is at:

https://domain.com/openapi/face/v1

Mercury Cloud API is served only over HTTPS to ensure your data privacy.

The domain.com might differ according to your service region. Please find this information in your service starting email.

3.2 Common parameters

Each API call requires a few common parameters, HTTP method, App ID, Access Key, and Secret Key.

GET, POST, and DELETE are the HTTP method used in Mercury Cloud. Refer to the API References for details on the method of each API. This method will also be used in API authentication.

The App ID, the Access Key, and the Secret Key are included in your service starting email. Please keep them in a safe place and do not disclose them to others. They will be used in setting the API URL and calculating the API auth token.

3.3 API authentication

All Mercury APIs require auth tokens to verify valid clients. There are two types of additional headers (x-date and Authorization) needed in each API call. If they are not included, you will get a 401 HTTP error code.

The x-date header

The x-date header uses an RFC-7231 formatted UTC date-time string.

For example:

x-date: Fri, 09 Jul 2021 01:51:02 GMT

This stands for 2021-07-09T01:51:02Z. Please notice that the x-date is the time of the GMT, not your local time.

The Authorization header

The Authorization header is generated based on a given URL path, HTTP method, App ID, Access Key, and Secret Key. For some APIs related to Features DBs, the DB ID is also required. The Authorization follows the following format.

Authorization: hmac username="{Access_key}", algorithm="hmac-sha256", headers="x-date request-line", signature="{Signature}"

A common Authorization header example is as follows.

Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="

The hmac username is your Access Key. Replace 005c5acf-5ea9-499c-8d3e-690413f9b5b9 with your own access key.

The signature is a base64 encoded string encrypted by HMAC-SHA256.

signature = encode_base64(hmac_sha256(key={secret_key},message=concat("x-date: ", {x-date}, "/n", {method}, " ", {URL path}, " HTTPS/1.1")))

Let us do it step by step. First, assemble the message before encryption.

A common message example before encryption is as follows.

x-date: Fri, 09 Jul 2021 01:51:02 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP/1.1

x-date is the same as the x-date header.

POST is the HTTP method. Make it consistent with the API you are going to use.

/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect is the URL path including the abc1a8a7-038f-4f9a-b98a-5b602978b135 part as the APP ID. Replace it with your own APP ID. Also, substitute this part with the URL path of your designated API. In some APIs, DB ID is also needed. For example,

x-date: Fri, 09 Jul 2021 01:51:02 GMT
GET /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/databases/aed37153-16b6-4f19-a479-302049e44000 HTTP/1.1

Where the aed37153-16b6-4f19-a479-302049e44000 is the DB ID.

Use the Secret key blFWSvhp9pRz2JnRHnfvkFeAuApClhKg to encrypt the first message we created.

x-date: Fri, 09 Jul 2021 01:37:00 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP/1.1

Then we will get

91427a38788c301667c604846b6011c550258230b69338de7598313b3d3b8be6

Encode it with base64. The signature is finalized as follows.

kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y=

Use this signature will complete the Authorization composition we saw above.

Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="

You can now use the x-date Header and the Authorization Header to make the API call of /openapi/face/v1/{app_id}/detect.

curl -X POST -d {} 'https://domain.com/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect' \
-H 'x-date: Fri, 09 Jul 2021 01:37:00 GMT' \
-H 'Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="'

3.4 Samples for making headers

Python

import base64
import datetime
import hashlib
import hmac
import urllib.parse

def generate_authorization_headers(access_key, secret_key, url, http_method):
    RFC7231_FORMAT = '%a, %d %b %Y %H:%M:%S GMT'
    xdate = datetime.datetime.utcnow().strftime(RFC7231_FORMAT)
    url_path = urllib.parse.urlparse(url).path
    signature = 'x-date: %s\n%s %s HTTP/1.1' % (xdate, http_method.upper(), url_path)
    crypto = hmac.new(secret_key.encode('utf-8'), signature.encode('utf-8'), hashlib.sha256)
    hmac_signature = base64.b64encode(crypto.digest()).decode('utf-8')
    authorization = '''hmac username="%s", algorithm="hmac-sha256", headers="x-date request-line", signature="%s"''' % (access_key, hmac_signature)
    return {
        "x-date": xdate,
        "Authorization": authorization
    }

JavaScript

//Requires crypto-js. See https://www.npmjs.com/package/crypto-js for more details.

function generate_authorization_headers(access_key, secret_key, url, http_method) {
    var today = new Date();
    var xdate = today.toGMTString();
    var reg = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
		var url_path = reg.exec(url)[1];
    var signature = "x-date: " + xdate + "\n" + http_method + " " + url_path + " HTTP/1.1";
    var hmac_signature = CryptoJS.HmacSHA256(signature, secret_key).toString(CryptoJS.enc.Base64);
    var authorization = "hmac username=\"" + access_key + "\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"" + hmac_signature +  "\"";
    return "-H 'x-date: " + xdate + "' -H 'Authorization: " + authorization + "'";
}

Kotlin

import java.text.SimpleDateFormat
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.net.URL

fun generate_authorization_headers(
     access_key: String,
     secret_key: String,
     url: String,
     http_method: String): Pair<String, String> {
    val rfc7231 = SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", Locale.US).apply {
        isLenient = false
        timeZone = TimeZone.getTimeZone("UTC")
    }
    val xDate = rfc7231.format(Date())
    val url_path = URL(url).getPath()
    val encodeData = "x-date: $xDate\n$http_method $url_path HTTP/1.1"
    val sha256Hmac = Mac.getInstance("HmacSHA256")
    val secretKey = SecretKeySpec(secret_key.toByteArray(), "HmacSHA256")
    sha256Hmac.init(secretKey)
    val signature = Base64.getEncoder().encodeToString(sha256Hmac.doFinal(encodeData.toByteArray()))
    val authorization = "hmac username=\"${access_key}\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"${signature}\""
    return Pair(xDate,authorization)
}

3.5 "Try it out" in the SwaggerHub

SwaggerHub offers interactive ways to let you test API calls directly from the browser using the "Try it out" button. Mercury Cloud Interactive API Documentation requires a special Authentication before you can use this function. Here is the guide to using the "Try it out" function in the Mercury Cloud Interactive API Documentation.

3.5.1 Prepare headers

Prepare the x-date header and the Authorization header, respectively, using the code samples.

3.5.2 Select the server

Click the Servers dropdown list and choose the server according to your service area.

Select the server

3.5.3 Authorize with the Authorization header

Click the "Authorize" button right to the Servers list.

Authorize

The following window will pop up. Paste the Authorization header into the "Value" textbox and click the "Authorize" button.

Available authorizations

The Authorization header has now been fixed. To re-authorize it, click the "Logout" button and re-do the steps above.

The Authorization header is time-sensitive, so you need to re-authorize it every time before you call the API.

Cancel the authorization

3.5.4 Enter the Parameters and have a try

Now we can try the API call. Take the List Feature Database API for example.

Try it out button

Click the "Try it out" button, the "Execute" button will show up.

Fill up the x-date and the app_id parameter and click the "Execute" button.

Execute

The API response will be displayed with some other related information.

Execute result