Designing Secure, Reliable APIs: Signatures, Encryption, Rate Limiting & More

Preface

In practice we often need to interact with third‑party platforms, either by calling their API or exposing our own API.

The challenge is to design an elegant API that satisfies security, repeatability, stability, and easy troubleshooting.

1. Signature

To prevent tampering, the request side concatenates

request parameters

+

timestamp

+

secret key

into a string and generates a

sign

using a hash algorithm such as

md5

. The sign is sent as a request parameter or header.

The gateway recomputes the sign with the same data and compares the two values. If they match, the request is considered valid and forwarded; otherwise a signature error is returned.

A timestamp is added to avoid replay attacks; the sign is valid only for a limited period (e.g., 15 minutes).

Two key‑management approaches are common: a pre‑agreed fixed

privateKey

, or an

AK/SK

pair where the caller sends

accessKey

in the header and the gateway retrieves the corresponding

secretKey

to generate a new sign.

2. Encryption

Sensitive data such as bank cards, amounts, or ID numbers must not be transmitted in plain text.

Base64 is frequently used for simple encoding/decoding. Data can be concatenated with a secret key and then encoded with the JDK 1.8+ Base64 utility.

<code>【加密前的数据】www.baidu.com<br/>【加密后的数据】d3d3LmJhaWR1LmNvbQ==</code>

Multiple Base64 encodings can increase security. The caller sends the encrypted string in a single

data

field, and the gateway decrypts it using the agreed key, algorithm, and iteration count.

3. IP Whitelist

To further protect the API, only IPs on a whitelist are allowed to access it. Requests from non‑whitelisted IPs are rejected with an access‑denied response. The whitelist can be enforced at the gateway or web‑firewall level (e.g., ModSecurity).

4. Rate Limiting

When third‑party platforms call the API, request volume can become uncontrolled, potentially causing service outages.

Three rate‑limiting strategies are typical:

Limit total requests per IP (e.g., 10,000 requests per minute).

Limit requests to a specific API per IP (e.g., 2,000 requests per minute).

Limit requests per AK/SK user (e.g., 10,000 requests per minute).

Implementation can rely on

nginx

,

redis

, or a dedicated gateway.

5. Parameter Validation

Validate required fields, data types, lengths, enum values, etc., to reject invalid requests early and avoid unnecessary database operations.

In Java, the Hibernate

Validator

framework provides annotations such as @NotEmpty, @Size, @Max, @Min, and custom annotations for dates or enums.

6. Unified Response

Inconsistent response formats make integration difficult. All APIs should return a single JSON structure, e.g.:

<code>{"code":0,"message":null,"data":[{"id":123,"name":"abc"}]}</code>

Errors such as signature failure or permission denial should use the same outer structure with appropriate

code

and

message

fields.

7. Unified Exception Handling

Expose only generic error information (e.g., code 500, message "Internal Server Error") to third parties, while logging detailed stack traces, SQL, and line numbers internally. The gateway can intercept exceptions and wrap them in the unified format.

8. Request Logging

Log URL, parameters, headers, method, response data, and latency for each request. Include a

traceId

to correlate logs. Logs can be persisted to MongoDB or Elasticsearch and optionally exposed via a UI for partner debugging.

9. Idempotent Design

Support repeated calls with the same parameters within a short window without creating duplicate records. Implement uniqueness via database unique indexes or store request IDs in Redis.

10. Record Count Limitation

Batch APIs should limit the number of records per request (commonly 500) to avoid timeouts and instability. Exceeding the limit should return a clear error.

11. Load Testing

Before release, perform stress testing (e.g., with JMeter or ApacheBench) to determine QPS limits and ensure the API can handle the configured rate‑limiting thresholds.

12. Asynchronous Processing

For long‑running or batch operations, push a message to a MQ and return immediately. The consumer processes the message later, and the caller can be notified via callback or polling.

13. Data Masking

Sensitive fields (e.g., phone numbers, bank cards) should be masked in responses, e.g.,

182****887

, to reduce exposure risk.

14. Complete API Documentation

A thorough API spec should include endpoint URL, HTTP method, request parameters and field descriptions, response schema, error codes, encryption/signature examples, full request demos, and extra notes such as IP whitelist configuration. Use consistent naming (e.g., camelCase) and version the URLs (e.g.,

v1/query/getCategory

).