Best Practices for Designing Secure and Robust API Controller Interfaces

In real‑world projects we often need to integrate with third‑party platforms by exposing or consuming controller APIs. Designing these APIs to be secure, repeatable, stable, and easy to debug is essential.

1. Signature

To prevent tampering, the client concatenates request parameters, a timestamp, and a secret key, then hashes the string (e.g., using md5 ) to produce a sign value. The server recomputes the signature with the same algorithm and compares the two values; a match indicates a valid request, otherwise a signature error is returned. Adding a timestamp limits the signature’s validity (e.g., 15 minutes) to mitigate replay attacks. Two key management approaches are common: a fixed privateKey shared by both parties, or an AK/SK pair where the access key is sent in the header and the secret key is looked up server‑side.

2. Encryption

Sensitive data such as passwords, bank cards, or identity numbers must not be sent in plain text. Asymmetric encryption (RSA) is widely used: the client encrypts the data with the public key, while the server decrypts it with the private key stored securely in the backend. An online RSA key‑pair generator can be used for testing.

3. IP Whitelist

To further protect the API, only IP addresses listed in an allow‑list are permitted to call the endpoint. Requests from non‑whitelisted IPs are rejected, and a web firewall (e.g., ModSecurity) can be added for additional defense.

4. Rate Limiting

Uncontrolled third‑party traffic can overwhelm the service. Rate limiting can be applied per IP, per specific API, or per AK/SK user, using tools such as nginx , redis , or an API gateway. Example limits: 10 000 total requests per minute per IP, 2 000 requests per minute per endpoint, etc.

5. Parameter Validation

Validate required fields, types, lengths, and enum values before reaching the database. In Java, the Hibernate Validator framework (annotations like @NotEmpty, @Size, @Max, @Min) is commonly used, with custom annotations for dates or enums when needed.

6. Unified Response Structure

All successful and error responses should follow a single JSON schema, e.g.:

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

Errors such as signature failure or permission denial return a consistent format with appropriate error codes and messages, simplifying client handling.

7. Unified Exception Handling

Internal exceptions (SQL errors, stack traces, etc.) must be caught at the gateway level and transformed into a generic error response, e.g.:

{
    "code": 500,
    "message": "服务器内部错误",
    "data": null
}

Detailed diagnostics are logged internally but never exposed to external callers.

8. Request Logging

Log request URL, parameters, headers, method, response data, and latency. Include a traceId to correlate logs across services. Logs can be persisted to databases such as MongoDB or Elasticsearch and optionally exposed via a UI for third‑party users.

9. Idempotency Design

To handle rapid duplicate submissions, ensure the API is idempotent: the first request creates a record, subsequent identical requests return success without creating duplicates. This can be achieved with unique database indexes or by storing a requestId in Redis.

10. Record Count Limiting

Batch endpoints should cap the number of records per request (commonly 500). Exceeding the limit returns a clear error, and the limit should be configurable in agreement with partners.

11. Stress Testing

Before release, perform load testing (using jmeter or apache bench ) to determine QPS limits and verify that rate‑limit thresholds are realistic.

12. Asynchronous Processing

For long‑running or batch operations, push a message to a message queue and return immediately. The consumer processes the job asynchronously, and the client can receive results via callback or polling a status endpoint.

13. Data Masking

Sensitive fields in responses (e.g., phone numbers, bank cards) should be masked, e.g., 182****887 , to reduce exposure risk.

14. Complete API Documentation

A thorough document should list endpoint URLs, HTTP methods, request/response fields, error codes, signing/encryption examples, demo requests, and extra notes such as IP whitelist activation. Consistent naming (camelCase), versioned URLs (e.g., /v1/query/getCategory ), and standardized field types improve maintainability.