REST API Design Like a Senior Engineer (REST, GraphQL, Networking, Pagination, Auth, Security)

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:

1. Plural noun plus ID: GET /posts/42, not GET /getPost?id=42. The HTTP method already carries the verb.

2. IDs, not names: /users/7, not /users/jane_old. A link built on the ID survives a rename.

3. One level of nesting: /posts/42/comments lists a post's comments. Comment 99 keeps its own short home at /comments/99.

4. Actions become resources: a like is POST /posts/42/likes, not POST /likeIt. An unlike deletes it.

5. 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?