Invoking API with Access Token¶
Follow the instructions below to invoke EnOS Edge APIs with the generated access token.
Before You Start¶
- Before calling EnOS Edge API with access token, you need to have the values of appKey, appSecret, accessToken, and timestamp ready.
Procedure¶
Constructing paramsData
¶
- Sort all the parameters of the API in the URL by ASCII order.
- Concatenate the sorted parameters and their values into a string.
- If the API request requires a JSON formatted request body, append the request body after the concatenated string to form the
paramsData
.
Note
The request body that is included in the paramsData must be identical with that is sent in the API request. Otherwise, the verification will fail.
Constructing apim-sign
¶
- Concatenate the values of
accessToken
,paramsData
,timestamp
, andappSecret
into a string to form thesignData
. - Encode the concatenated string
signData
in UTF-8 format and make a digest by SHA256 algorithm. - Convert the digest to hexadecimal format to generate the encrypted ciphertext
apim-sign
. See the following pseudo code:
sha256(signData).toLowerCase();
Constructing the Request Header¶
Include the following parameters in the API request header:
apim-accesstoken: accessToken
apim-signature: apim-sign
apim-timestamp: timestamp
Error Codes¶
Code | Description |
---|---|
0 | SUCCESS |
1001 | Repeated requests with duplicated encryption |
1002 | appKey does not exist |
1003 | The encryption is not valid |
1004 | Invalid parameter |
1005 | Internal service exception |
1202 | Parameter is empty |
1203 | Access token has expired |
1204 | Failed to refresh access token |
Sample¶
The following example shows the steps of invoking an API with access token.
Request URL¶
https://{apigw-address}/m/v1/b?k3=v3&k1=v1&k2=v2
Request Body¶
{
"count": 20,
"page": 1,
"desc": "描述"
}
Request Parameters¶
Parameter | Value |
---|---|
accessToken | xxxxaaaxxxx |
appSecret | xxxappSecretxxx |
timestamp | 1572574909697 |
Request Steps¶
Take the following steps to invoke the API with access token:
Sort the parameters k3, k1, k2 in the URL by ASCII order into k1, k2, k3.
Concatenate the sorted parameters and their values into a string
k1v1k2v2k3v3
.Concatenate the string
k1v1k2v2k3v3
and the request body into the following string:k1v1k2v2k3v3{ "count": 20, "page": 1, "desc": "描述" }
Concatenate the values of
accessToken
,paramsData
,timestamp
, andappSecret
into the following string:xxxxaaaxxxxk1v1k2v2k3v3{ "count": 20, "page": 1, "desc": "描述" }1572574909697xxxappSecretxxx
Encode the above concatenated string in UTF-8 format and make a digest by SHA256 algorithm. Convert the digest to hexadecimal format to generate the signature. See the following example:
59828328f6c1f9771015dc74e4929ae30f518a35a3d2353972c2ea46556fc981
Send the API request. See the following example:
curl https://{apigw-address}/m/v1/b?k3=v3&k1=v1&k2=v2 -X POST -H 'apim-accesstoken:xxxxaaaxxxx' -H 'apim-signature:59828328f6c1f9771015dc74e4929ae30f518a35a3d2353972c2ea46556fc981' -H 'apim-timestamp:1572574909697' -d '{ "count": 20, "page": 1, "desc": "描述" }'
Java Request Sample¶
import okhttp3.*;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Collections;
import java.util.List;
import java.util.stream.Collectors;
/**
* @author lixiangxin
* @date 2019/10/24 18:56
**/
public class EncryptUtils {
/**
* Encryption with Java Class
*
* @param str Encrypted string
* @return
*/
public static String getSHA256(String str) {
MessageDigest messageDigest;
String encodestr = "";
try {
messageDigest = MessageDigest.getInstance("SHA-256");
messageDigest.update(str.getBytes(StandardCharsets.UTF_8));
encodestr = hexString(messageDigest.digest());
} catch (NoSuchAlgorithmException e) {
return encodestr;
}
return encodestr;
}
private static String hexString(byte[] b) {
StringBuilder hs = new StringBuilder();
String stmp;
for (int n = 0; b != null && n < b.length; n++) {
stmp = Integer.toHexString(b[n] & 0XFF);
if (stmp.length() == 1) {
hs.append('0');
}
hs.append(stmp);
}
return hs.toString();
}
public static void main(String[] args) throws IOException {
String accssToken = "xxxxaaaxxxx";
String appSecret = "xxxappSecretxxx";
long timestamp = 1572574909697L; //System.currentTimeMillis();
String url = "https://{apigw-address}/m/v1/b?k3=v3&k1=v1&k2=v2";
String requestBody = "{\n" +
" \"count\": 20,\n" +
" \"page\": 1,\n" +
" \"desc\": \"描述\"\n" +
"}";
HttpUrl httpUrl = HttpUrl.parse(url);
if (httpUrl == null) {
return;
}
List<String> keys = new ArrayList<>(httpUrl.queryParameterNames());
Collections.sort(keys);
StringBuilder paramsData = new StringBuilder();
for (String key : keys) {
String value = httpUrl.queryParameter(key);
paramsData.append(key).append(value);
}
paramsData.append(requestBody);
String signData = accssToken + paramsData.toString() + timestamp + appSecret;
String apimSign = getSHA256(signData);
RequestBody body = FormBody
.create(MediaType.parse("application/json; charset=utf-8"), requestBody);
Request request = new Request.Builder().url(url).method("POST", body)
.addHeader("apim-accesstoken", accssToken)
.addHeader("apim-signature", apimSign)
.addHeader("apim-timestamp", timestamp + "")
.build();
String res = new OkHttpClient().newCall(request).execute().body().string();
System.out.println(res);
}
}