URLs, Path and Query Parameters
A member wants "books by Tolkien, newest first, 20 at a time". Another wants "book 42". Both requests go to BookNook, but they carry their details in different parts of the URL. Put each detail in the right part and your API reads like a sentence; put it in the wrong part and every caller has to guess.
The rule
The path says which thing; the query says how you want it.
A URL breaks into named pieces:
https://api.booknook.example/v1/books/42?fields=title,author#reviews
└─┬─┘ └─────────┬────────┘└─────┬────┘└─────────┬────────┘└───┬──┘
scheme host path query fragment- Path parameters are the variable segments of the path. In
/v1/books/42, the42is a path parameter. It identifies a resource: without it, you are pointing at a different thing. - Query parameters come after
?askey=valuepairs joined by&. They shape the answer: filter, sort, page, choose fields. Leave them out and you still reach the same resource, just a default view of it. - The fragment after
#never reaches the server; the browser keeps it.
GET /v1/books?author=tolkien&sort=-published&limit=20
GET /v1/members/7/loans?status=activeSpecial characters must be percent-encoded: a space becomes %20, and a literal & inside a value becomes %26, so it is not mistaken for a separator. A search for "war & peace" is sent as q=war%20%26%20peace.
The shortcut
Ask one question of each detail: "If I remove it, am I pointing at a different thing?" Yes → path. No, just a different view → query.
Member 7
Without it you would be looking at someone else's loans. It identifies → path:
/members/7.
Result: /v1/members/7/loans?status=active&sort=due. The trap is the reverse: /v1/books/sort/newest makes "sorting" look like a resource.
Drills
Answer fast — trust the rule.
In /v1/books/42?fields=title, which part is a path parameter?
Where should "only books published after 2000" go?
What does the server receive for https://api.booknook.example/v1/books#top?
A caller searches for the title R&D Handbook. How should the & travel inside q=?
Remember
- The path says which thing; the query says how you want it.
- Shortcut: "if I remove it, is it a different thing?" Yes → path, no → query.
- Trap: verbs or sort orders in the path, and unencoded
&,?or spaces in values.