APIs for Beginners
by Sergey Okinchuk

Chapter Eight · The Answer Does Not Fit in One Response

Real-World Data

Everything so far worked on one station at a time. This chapter is what happens when the answer is 214 stations, or a month of rides, and the API hands it over the way real APIs do: in pages, on a budget, sometimes from a saved copy, and always at an address carrying a version number. Five mechanisms — four announced in metadata you have been looking at since Chapter 4 without needing yet, and the fifth printed in the address you have typed since Chapter 2. By the end the Thursday report is a handful of well-aimed requests that finish inside the speed limit and survive the day Tandem renames a field.

No new machinery arrives in this chapter. Every mechanism here travels in the responses Chapter 2 took apart, in the envelope Chapter 4 taught you to read, and in headers that -i has been printing since Chapter 3. What changes is that you finally need them, because the questions have got big enough that the answers no longer arrive in one piece.

The five topics are one idea seen from five sides: an API is a shared resource, and asking well is how you get everything you need without taking more than your share. Pagination is how the answer arrives in slices. Filtering and sorting is how you ask for fewer slices. Rate limits are the posted speed. Caching is why some answers are older than they look. And versioning is why the address you type has held still all book while the API behind it kept improving.

The metadata was the map all along
data[ … ]
the fifty stations you actually asked for — the part everyone reads
page · total_pages · next_cursor
how much more there is, and how to ask for it — Topics 34 and 35
X-RateLimit-Remaining · Retry-After · Cache-Control · Age
how often you may ask, and how old this answer already is — Topics 36 and 37
api.tandem.example/v1
the edition of the promise all of it belongs to — Topic 38

Topics in This Chapter

Topic 34
Pagination: Data Comes in Pages
Fifty stations arrive and 214 exist, and the envelope said so all along. The numbered dialect, the cursor dialect, the one honest flaw of page numbers, and the walk that ends when the metadata says it does.
Scale
Topic 35
Filtering and Sorting
The Thursday report's core question, composed into one address: active only, emptiest first, stop at ten. Where the server's half of the work ends, and why an invented parameter answers a question you did not ask.
Scale
Topic 36
Rate Limits: The Rush-Hour Rules
Friday at 17:40 and the first 429 of the book. Sixty a minute, the counters that were in every response all along, waiting longer each time instead of hammering, and the three moves that put the ceiling out of reach.
Scale
Topic 37
Stale or Fresh: Caching Basics
The map says nine bikes and the API says seven, and both are telling the truth. Why copies get served, what max-age and Age confess, and the question that replaces "is this right?" for good.
Scale
Topic 38
Versioning: Why /v1 Is in the URL
Tandem renames free_bikes to available_bikes, and nobody's morning is ruined. Breaking against additive, where versions live, sunset dates, and the two characters you have typed on faith since Chapter 2.
Scale