An API is a promise about shapes. The value is entirely in that promise being kept, which is why the boring, predictable version beats the elegant one every time.

Decide the resources first

Write down your nouns, then the operations on each. GET /notes, GET /notes/:id, POST /notes, PATCH /notes/:id, DELETE /notes/:id. Plural, lowercase, consistent. If a route needs a verb in it, you've probably found a noun you haven't named yet.

Pick your shapes once and never vary

Every successful response the same shape. Every error the same shape. Timestamps always the same format. Field naming always the same convention. A caller learns your API once and then stops thinking about it — that is the entire product.

Status codes people expect

200 for fine, 201 for created, 400 for "you sent something wrong", 401 for "who are you", 403 for "I know who you are and no", 404 for missing, 409 for conflict, 422 for failed validation, 429 for slow down, 500 for "we broke it". Returning 200 with {"error": ...} inside is the mistake that makes clients unpleasant to write.

Build one endpoint completely

one-endpoint.txt
Build one endpoint: <METHOD> <path>

It does: <what>
Input: <fields and types>
Success returns: <shape>

Handle explicitly: invalid input, missing record, not authorised,
and the database failing. Give the status code and body for each.

Then show me the same endpoint's error shape as a template I can copy
for every other route.

Then make everything else match it. Consistency is cheap when you copy and expensive when you converge.

The things people forget

Pagination on every list, from the start. Adding it later is a breaking change.

Versioning. /v1/ in the path costs you nothing today and saves you an impossible conversation later.

Rate limiting, especially on anything unauthenticated or expensive.

Documentation that shows requests and responses. Not a schema dump — actual examples somebody can paste into curl.

The fastest way to find out whether your API is any good is to write a small client for it yourself. Every awkwardness shows up in the first ten minutes.