api-design-principles

name

api-design-principles

description

Interface design for APIs (REST, GraphQL, gRPC, library/SDK, CLI) — consistency, evolvability, error design, versioning, backward compatibility. Use when: designing APIs, reviewing API contracts, versioning decisions, error response design, choosing between REST/GraphQL/gRPC. Triggers: API design, REST, GraphQL, gRPC, versioning, backward compatibility, error response, pagination, rate limiting, OpenAPI

API Design Principles

Interface design judgment for APIs (REST, GraphQL, gRPC, library/SDK, CLI). Not architecture-level decisions (→ architect-thinking), not internal module design (→ design-philosophy).

Core Principles

• Consistency over cleverness: Uniform naming, consistent patterns across endpoints. Predictability reduces consumer cognitive load.
• Principle of Least Surprise: API behaves as consumers expect. No hidden side effects.
• Make common case easy, hard case possible: 80% of usage should be simple. Power users get escape hatches.

API Design Wisdom (Bloch)

Principle	Rationale
Design for inheritance or prohibit it	Expose only what you intend to support long-term
Return empty collections, not null	Avoid forcing null checks on every consumer
Use overloading judiciously	Prefer distinct method names over overloaded signatures
Minimize mutability	Immutable objects: simpler reasoning, thread-safe
Favor static factory methods over constructors	Named, can return subtypes, can cache

REST API Design

• Resource naming: Plural nouns (/users, not /getUsers). No verbs in URLs.
• HTTP method semantics: GET=read (idempotent), POST=create, PUT=full replace (idempotent), PATCH=partial update, DELETE=remove (idempotent)
• Status codes: Use correctly — 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Server Error
• Pagination: Cursor-based (scalable, no skipping) vs Offset-based (simple, skip-friendly). Default cursor for large datasets.
• Filtering/Sorting: Query parameters (?status=active&sort=-created_at), not path segments
• HATEOAS: Cost vs benefit. Useful for discoverable APIs, overhead for tight client-server coupling.

REST vs GraphQL vs gRPC

Dimension	REST	GraphQL	gRPC
Best for	CRUD, broad audience	Flexible queries, mobile	Internal services, high perf
Fetching	Over-fetching common	Client controls fields	Proto defines shape
Caching	HTTP caching natural	Complex (POST-based)	No HTTP caching
Schema	OpenAPI (optional)	Strong typed (required)	Protobuf (required)
Learning curve	Low	Medium	High
Streaming	SSE / WebSocket	Subscriptions	Bidirectional native

Error Design

• Structured response: { "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
• Machine-readable codes (stable) + human-readable messages (can change)
• RFC 9457 Problem Details: Standard format — type, title, status, detail, instance
• Don't leak internals: No stack traces, DB column names, or internal service names in production

Versioning & Backward Compatibility

Strategy	Pros	Cons
URL path (/v1/users)	Explicit, easy routing	Proliferates endpoints
Header (Accept: ...;version=2)	Clean URLs	Hidden, harder to test
Query param (?version=2)	Easy to add	Pollutes query space
Content negotiation	RESTful	Complex

• Safe changes: Adding fields, adding endpoints, adding optional params
• Breaking changes (need versioning): Removing/renaming fields, changing types/semantics
• Deprecation: Announce → Sunset header → grace period → remove. Never surprise consumers.
• Postel's Law: Be liberal in what you accept, conservative in what you send. Caveat: liberal acceptance can hide producer bugs.

Rate Limiting & Idempotency

• Rate limiting: Return 429 with Retry-After header. Document limits. Token bucket or sliding window.
• Idempotency keys: For non-idempotent operations (POST). Prevents duplicate processing on retry.

API Documentation

• OpenAPI/Swagger: Machine-readable spec → auto-generated docs, client SDKs, contract testing
• Examples over descriptions: Show request/response pairs. Real examples > abstract schemas.

Anti-Patterns

Pattern	Problem
Chatty API	Too many round trips → batch endpoints or GraphQL
God endpoint	One endpoint does everything → decompose by resource
Stringly-typed	Everything is string → use proper types, enums
Version in body	Routing nightmare → use URL or header
Breaking silently	No deprecation notice → sunset header + changelog

Reference Books

• Effective Java — Bloch (API design chapters)
• RESTful Web APIs — Richardson, Amundsen
• API Design Patterns — Geewax
• Designing Web APIs — Jin, Sahni, Shevat