REST API Design: Practical Guidelines

A well-designed API is a joy to use. A poorly designed one wastes hours in debugging and frustration. Here are practical guidelines from building and consuming dozens of APIs.

Use Nouns for Resources, Not Verbs

Good: GET /users/123. Bad: GET /getUser?id=123. The HTTP method already tells you the action. The URL should describe the resource. Use plural nouns consistently: /users, /posts, /comments.

Status Codes Matter

Return the right HTTP status code. 200 for success, 201 for created, 400 for bad request, 401 for unauthorized, 404 for not found, 500 for server error. Do not return 200 with an error message in the body. That breaks every HTTP client’s error handling.

Pagination is Not Optional

Any endpoint that returns a list must support pagination from day one. Use cursor-based pagination for real-time data and offset-based for stable datasets. Return total count and pagination metadata in the response.

Version Your API

Use URL versioning: /api/v1/users. When you need breaking changes, create v2 while keeping v1 running. Never break existing clients without warning.

Error Responses Should Be Helpful

Return structured error responses with a machine-readable code and a human-readable message. Include the field name for validation errors. A response like {error: code: INVALID_EMAIL, message: Email format is invalid, field: email} is infinitely more useful than {error: Bad Request}.

Document Everything

Use OpenAPI or Swagger to document your API. Include example requests and responses for every endpoint. Auto-generate client SDKs from your spec. The best documentation is the one that stays in sync with the code.