Query Parameters: Asking More Precisely
Vera does not want all two hundred and fourteen stations. She wants the active ones near the old town — and asking for exactly that is what query parameters are for. Chapter 2 introduced them as the URL's fourth room; this page is where they become a working skill, because precision in the ask is most of the craft of using an API.
curl "https://api.tandem.example/v1/stations?status=active&near=old-market"
Two parameters, chained with an ampersand: only active stations, only near Old Market. The answer drops from two hundred and fourteen stations to the dozen Vera actually wanted. One note about the quotes around the URL: the ampersand means something special to the terminal itself, and the quotes keep the address in one piece. Habit worth forming now: when a URL has parameters, quote it.
The Menu Is in the Documentation
Here is the rule that separates asking from wishing: you cannot invent parameters. The reference page for GET /stations lists what this endpoint accepts — status, near, and a few others you will meet in Chapter 8. That list is the menu. A parameter not on it does nothing, no matter how reasonable it sounds. Think of a coffee order: "coffee" is the path; "oat milk, no sugar, large" are the parameters — and they work because they are on the menu board. Ask for quantum foam and you get a blank look, not a new drink.
The Silent-Ignore Trap
Now the trap this page exists to install a flinch about. Misspell a parameter — staus=active — and most APIs will not error. They ignore the unknown name and answer as if you never asked: the full unfiltered list, verdict 200, everything looking perfectly healthy. The response is correct; it just answers a different question than the one you meant to ask. This is the classic quiet bug of API work: no error, wrong data. The habit that catches it: when a filter seems to change nothing, check the spelling against the docs before anything else.
When Characters Need Travel Clothes
Addresses cannot contain spaces or certain special characters, so values that include them travel encoded: a space becomes %20, and other characters have their own codes. This is called URL encoding, and the practical rule is two-sided. Recognize %-codes on sight so they read as spelling, not corruption — near=old%20market is just "old market" in travel clothes. And let tools do the encoding: browsers and GUI clients handle it automatically, and where this book's examples need it, they use values that need no dressing up.
Parameters or Path?
A fair question at this point: when does information go in the path, and when in the query? The rough rule: the path picks which thing — /stations/st_014 is Old Market. The query tunes which of many, in what form — ?status=active narrows the list. Rough is the honest word; real APIs draw the line in different places, and the documentation always settles it. You never have to guess, because the endpoint line in the docs shows exactly where each piece goes.
- "I can pass any parameter that makes sense." Only the documented ones do anything. The parameters table in the reference is the entire menu — everything else is silently ignored.
- "A misspelled parameter will give me an error." Usually not — it gives you a 200 and the unfiltered answer, which looks like success and is wrong. When a filter seems to do nothing, check spelling first.
- "%20 in a URL means it got corrupted." It is a space in travel clothes. Encoding is normal, reversible, and handled by decent tools — your job is only to recognize it.
- "The quotes around the URL are part of the address." They are for your terminal, keeping the ampersand from being interpreted as a command. The address is what is inside them.
- Filtering at the source is the difference between one precise request and an afternoon of scrolling. The Thursday report's core question will eventually be a single parameterized ask.
- The silent-ignore trap explains a whole genus of "the API returns wrong data" mysteries. Knowing it exists — and flinching correctly — is half the debugging before debugging even starts.
Knowledge Check
Where do you find out which query parameters an endpoint accepts?
- By trying likely names and seeing which ones change the answer
- In the endpoint's documentation, where the parameters table lists the menu
- By reading the response, which lists the filters that were available
- Parameter names are standardized across APIs, so every endpoint accepts the same ones
You send ?staus=active — misspelled. What does a typical API do?
- Returns a helpful error naming the unknown parameter so you can fix it
- Guesses that you meant status and applies the filter anyway
- Ignores it silently and returns the full unfiltered list with a 200
- Rejects the whole request outright, since one bad parameter spoils the entire ask
Why do the examples quote the URL when it contains parameters?
- Because the server requires quoted addresses when filters are used
- Because the ampersand is special to the terminal, and quotes keep the address whole
- Because quoting is how spaces get encoded into their travel clothes
- Because quoted requests are treated as higher priority by the API
You got correct