REST API Design: Naming, Status Codes, Pagination and Versioning

A well-designed API is predictable. Developers should be able to guess how an endpoint works before reading the docs.

Name resources, not actions

Use nouns and plural forms: /users, /posts/42/comments. Let the HTTP method express the action.

• GET reads a resource.
• POST creates one.
• PATCH updates part of one.
• PUT replaces one.
• DELETE removes one.

Use the right status codes

• 200 success, 201 created, 204 success with no body.
• 400 bad input, 401 not signed in, 403 not allowed, 404 not found, 409 conflict, 422 validation failed.
• 429 too many requests, 500 server error.

Never return 200 with an error inside the body.

Pagination, filtering and sorting

Accept ?page=2&limit=20&sort=-createdAt&status=published. Cap limit, and return metadata:

{ "data": [], "meta": { "page": 2, "limit": 20, "total": 134 } }

One error format

{ "success": false, "message": "Validation failed", "errors": [{ "path": "email", "message": "Invalid email" }] }

Consistent errors let clients display messages without special cases.

Version from the start

Prefix routes with /api/v1. When you must make a breaking change, ship v2 beside it.

Idempotency and safety

GET must never change data. PUT and DELETE should be safe to repeat. For payments and other risky POSTs, accept an idempotency key.

Document it

An OpenAPI file or a short README with examples is worth the time. Good docs reduce support questions to almost zero.

Takeaway

Nouns, correct status codes, bounded lists, one error shape and versioned routes make an API pleasant to consume.