Secure & Scalable API Design: Signatures, Encryption, Rate Limiting, and More

Signature

To prevent data tampering, API requests should be signed. The client concatenates request parameters, a timestamp, and a secret key, then generates a hash (e.g., MD5) to produce a sign value, which is sent as a request parameter or header. The gateway recomputes the signature using the same algorithm and compares the two values; a match indicates a valid request, otherwise a signature error is returned. Including a timestamp limits the request’s validity (e.g., 15 minutes) to mitigate replay attacks. Two key approaches for the secret are a shared static privateKey or an AK/SK pair where the access key (AK) is sent in the header and the secret key (SK) is retrieved server‑side.

Encryption

Sensitive data such as bank numbers or identity documents must be encrypted before transmission. A common method is Base64 encoding. Data is concatenated with a secret key, then encoded using Java 8's Base64 utilities:

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

Multiple rounds of Base64 can increase security. The client sends the encrypted string in a single data field; the gateway decrypts it using the agreed key, algorithm, and iteration count, then deserializes the parameters.

IP Whitelist

To further protect APIs, only IP addresses listed in an IP whitelist are allowed to access the service; others receive an access‑denied response. Firewalls such as ModSecurity can be added for additional protection.

Rate Limiting

When third‑party platforms call your API, uncontrolled request bursts can cause instability. Implement rate limiting by limiting (1) total requests per IP, (2) requests to specific endpoints, or (3) requests per AK/SK user. Tools like Nginx, Redis, or an API gateway can enforce these limits.

Parameter Validation

Validate request parameters for required fields, types, lengths, and enumerated values to reject invalid requests early. In Java, the Hibernate Validator provides annotations such as @NotEmpty, @Size, @Max, @Min, etc. Custom annotations may be needed for complex date or enum checks.

Unified Response Structure

Define a single response format (e.g., {"code":0,"message":null,"data":...}) for all API calls. Business exceptions should be caught by the gateway and transformed into this unified structure, avoiding multiple disparate response formats.

Unified Exception Handling

Capture all internal exceptions (SQL errors, stack traces, etc.) at the gateway level, log detailed information internally, and return a generic error response such as {"code":500,"message":"Internal Server Error","data":null} to external callers.

Request Logging

Log request URL, parameters, headers, method, response data, and latency. Include a traceId to correlate logs across services. Persist logs to databases like MongoDB or Elasticsearch and provide a UI for authorized third‑party users to view them.

Idempotency Design

Ensure that repeated identical requests within a short window do not create duplicate records. Use unique database constraints or store a requestId in Redis to guarantee idempotent behavior.

Record Count Limiting

For batch endpoints, limit the number of records per request (e.g., max 500) to prevent timeouts and maintain stability. Return a clear error when the limit is exceeded.

Performance Testing

Before release, conduct load testing (e.g., with JMeter or ApacheBench) to determine QPS limits and ensure the API can handle expected traffic, especially when rate limiting thresholds are set.

Asynchronous Processing

For long‑running or batch operations, send a message to a message queue and immediately return success. The consumer processes the task asynchronously. Clients can receive results via callbacks or by polling a status endpoint.

Data Masking

Mask sensitive fields (e.g., phone numbers, bank cards) in responses using asterisks (e.g., 182****887) to protect user privacy.

Complete API Documentation

A thorough API spec should include endpoint URLs, HTTP methods, request parameters with descriptions, response fields, error codes, encryption/signature examples, full request demos, and additional notes such as IP whitelist requirements. Use consistent naming conventions (e.g., camelCase) and version the API (e.g., v1/query/getCategory).