Filtering and Sorting
The Thursday report needs one thing above all: the emptiest active stations, worst first. Vera can now fetch all five pages of stations and squint at 214 rows in a spreadsheet — or she can ask the question properly and receive the answer as the answer, ten rows long, in a single response.
Letting the server do the selecting is not laziness. It is what the parameters are for. This page takes the query-parameter grammar from Chapter 3 and composes it: filters that shrink the list, sorting that decides the order, and a limit that stops at the part you actually wanted.
Filter at the Source
A filter is a query parameter that tells the server which items you want, so it leaves the rest out of the answer. Tandem's stations endpoint documents status= for active or out-of-service stations and near= for a part of town; the rides endpoint documents date ranges. Chain them with an ampersand exactly as in Chapter 3, and each one you add makes the response smaller and more nearly the thing you asked about.
Smaller matters more than it sounds. Filtering 214 stations down to the sixty active ones in the center turns five pages into two, which turns five requests into two, which is the difference between a sweep that fits comfortably inside the next page's speed limit and one that does not.
Sorting and Its Vocabulary
Sorting is asking the server for a particular order rather than accepting the one it happens to use. The common spelling is two parameters: sort names the field to order by, and order takes asc for ascending, smallest first, or desc for descending. So sort=free_bikes&order=asc means "emptiest station first".
Dialects vary. Some APIs write the same request as sort=-free_bikes, where the minus sign means descending; some call the parameter order_by. The documentation arbitrates, always, and the parameters table names the exact spelling this endpoint accepts. What does not vary is the consequence: when the server sorts, page one of the result is the top of the list, and you can stop reading after it.
Composition Is the Power Move
Filter, sort, and limit are three separate parameters, and putting all three in one address is where a beginner visibly becomes an API user. Each does one small thing; together they turn "give me everything" into "answer my question".
curl "https://api.tandem.example/v1/stations?status=active&sort=free_bikes&order=asc&limit=10"
Read that address as a sentence: active stations only, ordered by how many bikes are free, fewest first, and stop after ten. The response holds exactly the ten rows the report needs, in the order the report prints them. Fewer bytes, one page instead of five, and the walking loop from the previous topic disappears entirely — not because you learned a trick, but because you asked a narrower question.
The everyday version: you can ask the archivist for "the ten thinnest folders from the 2024 cabinet, thinnest first" and carry home a tidy stack, or you can wheel the whole cabinet home and do the same selecting on your kitchen floor an hour later. Same ten folders either way. Only one of them involves a cabinet in your kitchen.
When the Server Will Not
Sometimes no documented parameter does what you need — the report wants stations grouped by district and the endpoint has no district filter. The honest move is to fetch as narrowly as the menu allows, paginate properly, and finish the job in the spreadsheet. Knowing where the API's half of the work ends is part of fluency, not an admission of defeat.
What does not work is inventing the parameter you wish existed. Chapter 3 installed the flinch and it applies with full force here: an unrecognized parameter is usually ignored in silence, and the response comes back with a healthy 200 and a straight face, answering a question you did not ask. When a filter appears to change nothing, check its spelling against the parameters table before you check anything else.
- "Filtering in my spreadsheet gives the same rows, so it is the same thing." Same rows, wildly different cost: five requests and 214 objects against one request and ten. At Friday rush hour, which is the very next topic, that difference is the whole game.
- "sort on its own does what I meant." Ascending or descending is a choice, and the default differs from API to API. An unstated direction is a coin toss you will lose eventually; state
order, or read what the docs say the default is. - "If I can imagine the filter, the API probably has it." The parameters table is the entire menu. Anything off it is silently ignored, and the dangerous part is that the response still looks perfectly fine while answering a different question.
- "Sorting is something the tool at my end does." It can be, but then you must first fetch everything to sort it. Asking the server to sort is what makes page one of the answer the top ten instead of an arbitrary fifty.
- Composing a filter, a sort, and a limit into one legible address is the moment the Thursday report stops being an afternoon of spreadsheet work and becomes a question with an answer. That is the course's promise arriving in one line.
- Thinking in bytes, pages, and requests is exactly the habit the next topic makes mandatory. Readers who ask narrowly meet rate limits as a footnote; readers who fetch everything meet them as an outage.
Knowledge Check
Why is filtering with query parameters better than fetching everything and filtering yourself?
- The server's copy of the data is more accurate than yours
- Spreadsheets filter numeric columns unreliably at this size
- It costs many fewer requests, fewer pages, and fewer bytes
- Filtered endpoints are open to partners with extra scopes
What does ?status=active&sort=free_bikes&order=asc&limit=10 ask for?
- The ten emptiest active stations, emptiest first
- The ten fullest active stations, fullest first
- Active stations that currently hold ten bikes or fewer
- All stations sorted by bikes, with ten out of service
Vera types staus=active instead of status=active. What is the likely result?
- A 400 error naming the parameter the server did not recognize
- A 200 with every station, filtered by nothing at all
- The server corrects the spelling and applies the filter anyway
- A 401, because the request no longer matches her key's scope
The report needs stations grouped by district, and no district parameter is documented. What is the professional move?
- Add a district parameter anyway and see what comes back
- Guess at an undocumented districts endpoint on the same host
- Report the missing grouping to Jonas as a defect in the API
- Filter as narrowly as the menu allows, then group at your end
You got correct