Designing REST APIs That Other Developers Enjoy Using

An API is a user interface for developers. The same principles apply: be consistent, be predictable and fail helpfully. Most of the quality comes from a handful of decisions you can make in the first week.

Name resources, not actions

Use nouns for resources and let HTTP methods express the action.

• GET /posts lists posts and GET /posts/42 fetches one.

• POST /posts creates a post.

• PATCH /posts/42 updates part of a post; DELETE /posts/42 removes it.

Pick plural or singular and stick to it. Consistency matters more than which you choose.

Use status codes honestly

• 200 for success, 201 when something was created.

• 400 for malformed input and 422 when the input is well-formed but invalid.

• 401 when the caller is not authenticated and 403 when they are not allowed.

• 404 for unknown resources and 409 for conflicts.

Errors that help

A useful error tells the caller what went wrong and where. Return the same shape for every error so clients can handle them in one place.

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": { "email": "Must be a valid email address." }
  }
}

Pagination from day one

Never return an unbounded list. Accept limit and a cursor or page parameter, and return enough information to request the next page. It is far harder to add pagination later than to include it at the start.

Versioning without drama

Breaking changes will happen. Put a version in the path (/v1/posts) or a header, and treat additions such as new optional fields as non-breaking. Announce deprecations early and keep the old version running for a defined period.

Security basics

• Always use HTTPS.

• Authenticate every request that touches private data and check authorization on the server, never only in the client.

• Validate and limit input sizes.

• Rate-limit sensitive endpoints such as login.

• Never include secrets or internal stack traces in responses.

Document as you build

A short, accurate reference with one working example per endpoint is worth more than a long, outdated specification. Keep the examples runnable.