API design is one of those disciplines where the principles are well established but widely ignored in practice. Here are the things that genuinely matter for building APIs other developers will want to use.
RESTful Design Done Right
Most APIs claim to be RESTful; few actually are. The key principles that are most often violated: Resource-oriented URLs (nouns, not verbs): `/users/123/orders` is REST; `/getUserOrders?userId=123` is RPC disguised as REST. The URL identifies the resource; the HTTP method expresses the action. Correct HTTP methods: GET (idempotent, cacheable, no body); POST (create a new resource, not idempotent); PUT (replace a resource entirely, idempotent); PATCH (partial update, body contains only the fields to change); DELETE (remove a resource, idempotent). Status codes that mean what they say: 200 OK (success with body); 201 Created (resource created, include Location header pointing to the new resource); 204 No Content (success without body — DELETE responses); 400 Bad Request (client error — invalid input); 401 Unauthorized (authentication required); 403 Forbidden (authenticated but not authorised); 404 Not Found; 409 Conflict (state conflict — creating a duplicate unique resource); 422 Unprocessable Entity (valid JSON but fails business validation); 429 Too Many Requests (rate limit); 500 Internal Server Error. The common error: returning 200 OK with `{“success”: false, “error”: “not found”}` instead of 404. This breaks all HTTP tooling (caches, proxies, monitoring).
Response Design
Consistent error format: every error response should have the same structure — `{“error”: {“code”: “USER_NOT_FOUND”, “message”: “No user with id 123 exists”, “details”: {…}}}`. The `code` field allows clients to handle specific errors programmatically; the `message` is for humans and logging. Pagination: for list endpoints, always paginate; never return unbounded lists. Two common approaches: offset/limit (`?offset=0&limit=20`) — simple, allows jumping to page N; cursor-based (`?after=eyJ…`) — better for large datasets and real-time data (consistent even if data is added during pagination). Include pagination metadata in the response (`{“data”: […], “pagination”: {“total”: 1234, “next_cursor”: “eyJ…”}}`). Versioning: version in the URL path (`/v1/users`) is the most practical approach — clear, easy to route, explicit. Header versioning (`Accept: application/vnd.myapi.v1+json`) is theoretically purer REST but operationally harder. Deprecation: set `Sunset` and `Deprecation` headers on deprecated endpoints to give clients advance notice.
What Actually Makes APIs Good to Use
Documentation with examples: every endpoint should have a request example and a response example. Abstract descriptions are useless; concrete examples make APIs usable. Authentication clarity: be explicit about how authentication works, what tokens look like, how to refresh them, and what happens when they expire. Idempotency keys: for POST endpoints that should not be duplicated (payment processing, order creation), support idempotency keys — a client-provided UUID in the header that the server uses to detect and return the original response for duplicate requests. Rate limit transparency: include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers in responses so clients know their usage and can implement backoff. The most common API design mistake: inconsistency. An API where some resources use camelCase, some snake_case, some use `id`, some `uuid`, error formats differ by endpoint, and pagination is implemented differently across endpoints is harder to use than an API with imperfect but consistent conventions.
