Most first APIs are a list of URLs, one per button. A senior engineer's API follows a few rules, so you can guess every address.
That list breaks once a second developer joins.
Here are the 5 rules that fix it:
Plural noun plus ID: GET /posts/42, not GET /getPost?id=42. The HTTP method already carries the verb.
IDs, not names: /users/7, not /users/jane_old. A link built on the ID survives a rename.
One level of nesting: /posts/42/comments lists a post's comments. Comment 99 keeps its own short home at /comments/99.
Actions become resources: a like is POST /posts/42/likes, not POST /likeIt. An unlike deletes it.
A verb only when no noun fits: POST /posts/42:archive, for actions that leave nothing to store.
You can always add servers when traffic grows. An API is harder to change, because installed apps keep calling the old shape for years.
I walk through all of this in a full REST API course on my YouTube channel, designing one photo-sharing app from zero: https://youtu.be/BvtIqaiabJA
Over to you: which URL in your current API would a new teammate never guess?
Top comments (1)
One thing I'd add to the pagination section is that cursor-based pagination doesn't automatically guarantee a consistent view of the data.
Imagine an activity feed backed by PostgreSQL, sorted by
created_at DESC. You're using keyset pagination with(created_at, id)as the cursor. While a client is fetching subsequent pages, new records are inserted, existing records are deleted, and some entries get updated.Keyset pagination avoids the growing cost of large OFFSET queries, but it doesn't give you snapshot consistency across multiple requests. Depending on the product requirements, you might need a snapshot boundary, a versioned dataset, or a server-side cursor to keep the traversal predictable.
This becomes particularly important in financial transaction histories and audit logs, where silently skipping or repeating records isn't just a pagination bug. It's a data integrity problem.