An API is the language your system uses to talk to any other application. The more predictable it is, the fewer the mistakes, and the easier it is to build on for years.

Nouns for resources, verbs from HTTP

Use plural nouns for resources and let the HTTP method carry the action:

  • GET /invoices list invoices.
  • POST /invoices create one.
  • GET /invoices/42 a specific invoice.
  • PATCH /invoices/42 partial update.
  • DELETE /invoices/42 delete.

Honest status codes

200 for success, 201 for creation, 400 bad request, 401 unauthenticated, 403 forbidden, 404 not found, 422 invalid data. Do not return 200 with an error hidden in the body.

Understandable errors

Return a consistent error shape with a code, a message and the offending field, so developers can handle it easily.

Security

  1. Require authentication for anything private, and never put keys in URLs.
  2. Check authorisation per resource, not only in the UI.
  3. Validate input and use prepared statements.
  4. Rate-limit requests to reduce abuse.

Versions and pages

Put the version in the path (/v1) so you can evolve without breaking clients, and paginate long lists.

An API that never surprises its users is a well-designed API.