API Design
Principles and practices for designing clear, consistent, and evolvable programming interfaces that facilitate integration between systems.
seed#api#rest#graphql#design#openapi#contracts
What it is
API design is the discipline of creating clear, consistent, and easy-to-use programmatic interfaces. A well-designed API is predictable, documented, and evolvable without breaking existing consumers.
API styles
| Style | Characteristics | Ideal for |
|---|---|---|
| REST | Resources, HTTP verbs, stateless | CRUD, public APIs |
| GraphQL | Query language, typed schema | Flexible frontends |
| gRPC | Protocol Buffers, streaming | Internal microservices |
| WebSocket | Bidirectional, real-time | Chat, notifications |
REST design principles
- Plural resource names (
/users, not/user) - Semantic HTTP verbs (GET, POST, PUT, DELETE)
- Appropriate status codes (201 Created, 404 Not Found)
- Versioning (URL path or header)
- Consistent pagination
- HATEOAS for discoverability
API-First / Design-First
Define the API contract before implementing. Tools like OpenAPI allow generating documentation, SDKs, and mocks from the specification. Connects with spec-driven development.
Why it matters
A poorly designed API becomes a contract you cannot break. Every decision — naming, versioning, error handling — solidifies once there are consumers. Investing in design before publishing saves months of painful migrations later.
References
- API Design Patterns — JJ Geewax, 2021.
- OpenAPI Specification — Industry standard.
- Google API Design Guide — Google, 2024. Best practices guide for API design.