跪拜 Guibai
← All articles
Backend · Interview · Java

Designing Production-Grade Open APIs: From Contract to Rate Limiting, With Every Pitfall Addressed

By Rain的Java大神之路 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

This guide packs the entire API hardening playbook into one place: security, idempotency, rate limiting, and observability are usually learned via production incidents, but here they come with ready-to-adapt Java code and a replay checklist that maps directly to common interview questions.

Summary

A comprehensive guide walks through the full lifecycle of building a production API, from clarifying the scenario before writing a line of code to a twelve-point checklist of technical pitfalls. The approach starts with four questions (who calls it, what concurrency, consistency needs, iteration pace), then lays out five design principles: semantic clarity, fault tolerance first, security baseline, observability, and backward-compatible evolution.

The meat of the guide is practical implementations. Contract design covers RESTful resource modeling, a unified JSON response envelope with traceId, segmented error codes, cursor pagination, validation with @Valid, and global exception handlers that never leak stack traces. Security goes beyond HTTPS with an AppKey/AppSecret HMAC-SHA256 signature scheme plus timestamp and nonce checks to stop replay attacks, all with Java code.

For idempotency, the guide compares five approaches and recommends a Redis Lua annotation with a unique index as backstop, distinguishing 'processing' and 'done' states and deleting the key on failure. Rate limiting uses a Redis Lua token bucket and a ZSet sliding window to avoid fixed-window spikes. Later sections cover performance, versioning strategies, observability with traceId propagation, and two advanced interview scenarios (high-concurrency ordering and async report export).

Takeaways
— Before writing code, clarify four things: who calls the API, the concurrency volume (QPS), consistency tolerance, and iteration pace.
— Five design principles govern the whole approach: semantic clarity, fault tolerance first, security baseline, observability, and backward-compatible evolution.
— A request passes through four layers—gateway, business, governance, and delivery—and the rule is to push as much as possible to the gateway.
— RESTful conventions: plural nouns, HTTP methods for actions, max 3 path levels, lowercase with hyphens, version in the URL path.
— A unified response envelope includes code, message, data, traceId, and timestamp; business codes are decoupled from HTTP status codes.
— Error codes are segmented by range: 1xxxx for parameters, 2xxxx for auth, 3xxxx for business, 4xxxx for system.
— Cursor pagination (id < last_id) avoids deep-page performance problems; all list endpoints must enforce a size limit.
— Security requires HMAC-SHA256 signatures on sorted parameters plus a body digest, timestamp window check, and nonce stored in Redis via SETNX.
— Use constant-time comparison for signatures and never return stack traces to callers—only logs get the stack, the external response gets a traceId.
— Idempotency is not concurrency control; use Redis Lua to atomically check-and-set a key, distinguish PROCESSING/DONE states, and delete the key on any failure.
— A database unique index should serve as the backstop behind Redis idempotency interception.
— Distributed rate limiting uses Redis Lua token bucket; sliding window via ZSet avoids the fixed-window boundary spike.
— Versioning via URL path, only add fields never modify/delete, keep old versions for 3-6 months, and gray-release by AppKey or userId modulo.
— Observability requires traceId propagation through MDC, thread pools, and MQ headers, plus layered logs and Grafana alerts on error rate and P99 latency.
— For long-running exports, return 202 Accepted with a taskId and let callers poll or register a webhook.
Conclusions

The guide's insistence on deleting the idempotency key on exception is a rare, concrete operational detail most tutorials skip; it's the difference between a system that recovers and one that permanently blocks retries.

By putting atomicity into Redis Lua scripts for both idempotency and rate limiting, the author demonstrates a pattern: when you need distributed atomicity, push it to the datastore instead of coordinating from application code.

Separating idempotency from concurrency control clarifies a common confusion: one handles repeated requests, the other handles simultaneous writes. Conflating them leads to over-engineered locks.

Concepts & terms
HMAC-SHA256
A keyed hash algorithm used to sign API requests. The server recomputes it from sorted parameters and compares with a constant-time comparison to detect tampering.
Nonce
A one-time random number sent by the client. The server stores it in Redis with SETNX to detect and reject replay attacks within a validity window.
Token bucket
A rate limiting algorithm that maintains a bucket of tokens replenished at a fixed rate, allowing controlled bursts up to the bucket capacity while smoothing overall throughput.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗