18 Essential API Design Rules Every Backend Developer Should Follow

1. Signature

To prevent tampering, API requests should be signed. The client concatenates request parameters, timestamp, and a secret key, hashes them (e.g., MD5) to produce a sign, which is sent as a parameter or header. The gateway recomputes the sign and validates it, rejecting mismatches.

Including a timestamp limits the sign's validity (e.g., 15 minutes) to prevent replay attacks. The secret key can be a fixed privateKey or an AK/SK pair where the SK is used for signing.

2. Encryption

Sensitive data such as passwords, bank cards, or IDs must be encrypted before transmission. Symmetric algorithms like AES can be used on the client side, possibly with a public key, and the server decrypts with the corresponding key before processing.

3. IP Whitelist

Restrict API access to approved IP addresses. Requests from non‑whitelisted IPs are denied, and a web firewall (e.g., ModSecurity) can provide additional protection.

4. Rate Limiting

Control request volume to avoid overload. Limits can be applied per IP, per specific API, or per AK/SK user, using tools such as Nginx, Redis, or an API gateway.

5. Parameter Validation

Validate required fields, types, lengths, and enumerations to reject invalid requests early. In Java, the Hibernate Validator provides annotations like @NotEmpty, @Size, @Max, etc.

6. Unified Response Format

Define a single JSON structure (code, message, data) for all successful and error responses. The API gateway should capture business exceptions and convert them to this unified format.

7. Unified Exception Handling

Capture and wrap internal exceptions (stack trace, DB info, error codes) into a generic error response (e.g., code 500, message "Internal Server Error") while logging detailed information internally.

8. Request Logging

Record request URL, parameters, headers, method, response data, and latency, preferably with a traceId to correlate logs. Logs can be stored in MongoDB or Elasticsearch and optionally exposed to third‑party users.

9. Idempotency

Ensure repeated requests with the same parameters within a short window do not create duplicate data. Implement via unique database indexes or storing requestId in Redis.

10. Record Count Limiting

Limit batch request sizes (e.g., max 500 records) to prevent timeouts, and enforce pagination for large result sets.

11. Stress Testing

Perform load testing (e.g., with JMeter or ApacheBench) to verify QPS limits and server capacity before deployment.

12. Asynchronous Processing

For long‑running operations, publish a message to a queue and return immediately. The client can receive results via callbacks or polling.

13. Data Masking

Mask sensitive fields (e.g., phone numbers) in responses using asterisks to reduce data leakage risk.

14. Complete API Documentation

Include endpoint URL, method, parameters, response schema, error codes, encryption/signature examples, demo requests, and notes such as IP whitelist requirements. Use consistent naming conventions (e.g., camelCase) and define field types and formats.

15. Request Methods

Choose GET for parameter‑less queries and POST for requests with payloads, as POST supports larger request bodies.

16. Request Headers

Place common data such as traceId or authentication tokens in HTTP headers rather than query parameters.

17. Batch Operations

Design APIs to accept multiple IDs or records in a single request to avoid proliferating single‑item endpoints.

18. Single Responsibility

Separate endpoints by client type (web vs mobile) and by operation (normal vs fast order) to keep interfaces clear and maintainable.