Chapter Six · The Manual, Raided
Reading the Documentation
Every request in this book so far was one the book handed you. Real work hands you a link instead, and expects you to find your own way from there. This chapter is that skill. Reference pages turn out to be the same five parts everywhere, learnable once and usable on any API. Half of them are generated from a single machine-readable file, which is why they all feel oddly familiar. A second key with a different prefix gives you a place to be wrong for free. And on the day the page and the server disagree, one command settles it, because the server is the API and the page is only a copy.
Vera now has a key, a command line, and the ability to read what comes back. What she does not have is a list of what she is allowed to ask for. Chapter 3 handed her two filters by name — and nothing so far says what else /v1/stations accepts, what each parameter is called, or what it will do to the answer. That list exists in exactly one place, and Jonas has been linking to it in every email: the documentation.
Documentation has a bad reputation it half deserves. Read start to finish it is unbearable, because it was never meant to be read that way. It is a reference, like a dictionary or a parts catalogue: you arrive with a specific question, you find the one page that answers it, and you leave. This chapter teaches that arrival. By the end of it you can walk into the documentation of an API you have never heard of and be useful inside two minutes.
parameters, response schema, example
the API as promised
the fields that actually arrive
the API as it is