tech

API Design Principles

apidesignrest

Good APIs feel obvious. Bad APIs require reading documentation for every call.

Principles

  • Consistent naming: use nouns, not verbs. Use /users, not /getUsers
  • Idempotent where possible: same request, same result
  • Pagination by default: never return unbounded lists
  • Error messages that help: include what went wrong and how to fix it

Status Codes

  • 200: success
  • 201: created
  • 400: bad request (client error)
  • 404: not found
  • 500: server error (something broke)

A well-designed API is a competitive advantage. Developers choose tools they enjoy using.