A well-designed API is a joy to work with. A poorly designed one generates support tickets, confused developers, and brittle integrations. These principles guide how we design APIs that last.
Resource-Oriented Design
Structure your API around resources (nouns), not actions (verbs). Use GET /users instead of GET /getUsers. Use POST /orders instead of POST /createOrder. HTTP methods already convey the action: GET retrieves, POST creates, PUT replaces, PATCH updates, DELETE removes.
Consistent Naming Conventions
Use plural nouns for collections (/users, not /user). Use lowercase with hyphens for multi-word resources (/user-profiles, not /userProfiles). Nest related resources logically: /users/123/orders retrieves orders for user 123.
Be consistent across your entire API. If one endpoint uses camelCase in response fields, every endpoint should. Inconsistency creates confusion and bugs.
Meaningful HTTP Status Codes
- 200 — successful GET/PUT/PATCH requests
- 201 — successful POST (resource created)
- 204 — successful DELETE (no content to return)
- 400 — invalid client input
- 401 — unauthenticated requests
- 403 — unauthorised requests
- 404 — missing resources
- 422 — validation errors
- 429 — rate limit exceeded
- 500 — server errors
Using the right status code means clients can handle responses programmatically without parsing error messages.
Pagination, Filtering, and Sorting
Every list endpoint should support pagination from day one. Use cursor-based pagination for large datasets (more performant than offset-based). Support filtering through query parameters: /orders?status=pending&created_after=2025-01-01. Support sorting: /users?sort=created_at&order=desc.
Versioning
Version your API in the URL path (/api/v1/users). Header-based versioning is technically purer but harder for developers to work with. When introducing breaking changes, maintain the old version for a documented deprecation period.
Error Responses
Return structured error responses with a consistent format. Include an error code (machine-readable), a message (human-readable), and field-specific details for validation errors. Avoid exposing internal implementation details (stack traces, database errors) in production error responses.
Documentation
An undocumented API is an unusable API. Document every endpoint with its URL, method, parameters, request body format, response format, and possible error codes. Use OpenAPI/Swagger for interactive documentation that developers can test directly.
The Design Process
Design your API contract before writing implementation code. Share the design with the teams that will consume it. Iterate on the design based on their feedback. Building the right API interface first prevents expensive rewrites when consumers discover the design doesn’t meet their needs.
At Masterpiece Designs, API design is a collaborative process between backend and frontend teams, resulting in interfaces that serve both sides well.