API Design Principles We Follow on Every Project

After building APIs for dozens of projects, we've settled on a set of principles that consistently produce systems that are easy to consume, easy to maintain, and easy to evolve.

Resource-oriented URLs. Every endpoint represents a noun, not a verb. /orders not /getOrders. /orders/{id}/cancel not /cancelOrder. This sounds obvious but it's surprising how often it gets ignored under deadline pressure.

Consistent error responses. Every error returns the same shape: a status code, a machine-readable error code, and a human-readable message. Clients should never have to guess what went wrong. We use a standard envelope: { "error": { "code": "ORDER_NOT_FOUND", "message": "No order with id 123 exists" } }.

Versioning from day one. We version in the URL path (/v1/, /v2/) rather than headers. It's less elegant but far more debuggable — you can see the version in logs, browser history, and curl commands without extra tooling.

Rate limiting on every endpoint. Not just the obvious ones. We use a token bucket algorithm implemented in Redis. Limits are returned in response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) so clients can implement backoff correctly.

Documentation that stays current. We generate OpenAPI specs from code annotations, not from a separate documentation process. If the code changes, the docs change. We've tried the reverse and it always drifts.

Idempotency keys for mutations. Any POST that creates or modifies state accepts an optional Idempotency-Key header. If the same key is sent twice, the second request returns the result of the first without executing again. This makes retry logic safe for clients.

These aren't revolutionary ideas. They're the result of maintaining APIs over years and learning what breaks down in production.