RESTful conventions, versioning, and error responses that make integrations and refactors less painful.
Good API design is mostly about consistency and clarity. Here’s a short checklist I follow.
Resource-Oriented URLs
Use nouns and HTTP verbs: GET /users, POST /orders, PATCH /orders/:id. Avoid verbs in the path; the method already says what you’re doing.
Stable Error Shape
Return a consistent structure: {"error": {"code": "...", "message": "..."}}. Same format for validation errors, auth errors, and server errors. Clients can handle one shape.
Version Early If You Might Break Things
If you’re not 100% sure the contract is final, put a version in the path or header (/v1/users or Accept: application/vnd.api+json;version=1). It’s easier than renaming or breaking fields later.
Pagination and Filtering
For lists, support limit and cursor (or offset). Document the default. Add a few filters that you know clients will need instead of a generic “query” that’s hard to optimize.
APIs outlive the first release. A little structure now saves a lot of pain later.
Comments
Sign in to leave a comment.