Designing Open Platform APIs: Application Registration, OAuth2 Authorization, Request Parameters, and Signature Verification

Recently I have integrated many open platforms such as Taobao, JD, Kuaishou, and Douyin. Although the integration itself is not technically challenging, I wanted to summarize a reusable design pattern for open‑platform APIs.

Key Concerns for Open Platforms

Usability: simple, self‑descriptive request parameters for quick onboarding.

Security: protect user data exposed on the public network.

Stability: ensure reliable service for upstream partners.

…

Service‑Provider Application

An open platform is typically divided into three parts:

Access Guide – helps partners connect to the platform.

API Documentation – assists developers in implementing business functions.

Application – the identity of the partner on the platform.

The first step for a partner is to create an application, which enables the platform to identify the partner and apply rate‑limiting, permission control, etc.

Basic Attributes

Each partner application usually has three core attributes: appid: unique identifier of the partner application. appsecret: secret key used for signing and identity verification. Authorization Callback URL: URL invoked after the user grants permission.

Authorization

Authorization is not the platform granting rights to the partner application; it is the end‑user (e.g., a shop owner) granting the partner application permission to access their data.

Three roles are required to complete the authorization flow:

Open Platform – provides the authorization page and redirects to the partner's callback URL with the authorization data.

Customer – completes the authorization on the platform's page.

Partner Application – receives the callback, binds the user, and stores the authorization information.

Alternatively, the partner can authenticate directly using appid + appsecret when no third‑party user interaction is needed.

OAuth2 Authorization Mechanism

OAuth2

is the de‑facto standard for web authorization (e.g., GitHub login, WeChat public account authorization).

For a deeper dive, see my previous article "A Complete Guide to OAuth2 and Spring Security Integration".

Request Parameters

Parameters are divided into two categories: System Parameters: required for every API call (e.g., appid, appsecret, timestamp, sign). Business Parameters: specific to the business operation (e.g., status for order queries).

Business parameters are usually sent as application/json or application/x-www-form-urlencoded in the POST body and must participate in the signature.

Request Signature

The purpose of a signature is to prevent tampering. Common algorithms include MD5, SHA, or asymmetric encryption for high‑security scenarios.

A typical signature generation method is:

sign = appsecret + appid + timestamp + sorted(businessParameters) + appsecret

Pseudocode

String appid = "abcd";
String appsecret = "12345";
Long timestamp = 948758686;
// Ordered map, sorted by key
Map<String, Object> requestBody = new TreeMap<>();
requestBody.put("a", 1);
requestBody.put("b", 21);
requestBody.put("c", 2);
// Convert to JSON string
String jsonBody = JSON.toJSONString(requestBody);
String sign = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);

Signature Verification

The verification steps mirror the generation steps:

String appid = request.getParameter("appid");
String appsecret = request.getParameter("appsecret");
Long timestamp = request.getParameter("timestamp");
// Retrieve business parameters and sort them
Map<String, Object> requestBody = new TreeMap<>(JSON.parseObject("post request parameters"));
String jsonBody = JSON.toJSONString(requestBody);
String sign = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);
String originSign = request.getParameter("sign");
if (Objects.equals(sign, originSign)) {
  // Signature valid
} else {
  // Signature invalid
}

Conclusion

The above outlines a practical approach to open‑platform API design, covering application registration, OAuth2 authorization, parameter handling, and signature mechanisms. Future articles will explore SDK design for such platforms.

I am a Java developer who loves finding bugs. If you find this useful, please give a like!