Designing APIs That Your Future Self Won’t Curse

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.