The Anatomy of a Reference Page

Vera opens Tandem's documentation for the first time and finds a wall: dozens of endpoints down the left, unfamiliar words everywhere, no obvious place to start. The instinct is to begin at the top and read. That instinct is the reason people find documentation exhausting, because a reference — a document organized for looking things up rather than for reading through — punishes anyone who reads it in order.

Reference pages have a fixed anatomy. Endpoint line, parameters, example, response schema, error list: five parts, in roughly that order, on essentially every API on earth. They wear different colors and different fonts, and that is the whole of the difference. It works like a dictionary entry — headword, pronunciation, part of speech, senses, examples — a shape you learned once as a child and now apply to any word without thinking. Nobody reads dictionaries. Everybody uses them.

The Endpoint Line

At the top of the page sits one line, usually in a box, usually bigger than everything around it: GET /v1/stations/{id}. It is the address of this particular promise. The verb says what kind of act this is, and after Chapter 2 you read it for free: GET looks, POST creates, DELETE removes. The path says which counter, and which thing at that counter.

The curly braces are a convention rather than a character you type. {id} means "a value of yours goes here" — the station code, in this case. Vera fills it in and the line becomes a real address: /v1/stations/st_014. Sending the braces along as literal text is one of the most common first errors in API work, and it produces a tidy 404 that Chapter 7 will teach you to read without flinching.

The Parameters Table

Under the endpoint line is a grid, and by now you know every word in its column headings. Name is what the parameter is called. In says where it travels: in the path, in the query string after the question mark, in a header, or in the body. Type says what shape of value it wants, using Chapter 4's vocabulary — string, number, boolean. Required says whether the request works without it. Default says what the server assumes when you leave it out.

Read the required column first. Almost every parameter in almost every table is optional with a sensible default, which means a table of twenty rows usually describes an endpoint you can call with two of them. Length here signals flexibility, not difficulty, and treating a long table as a warning sign is a good way to talk yourself out of an easy request.

The Response Schema

The schema is the list of fields that will come back, with their types and their nesting. It is Chapter 4's work done in advance: instead of sending a request and hunting through the answer for location.lat, you read the schema and know that path is there before you type anything.

This is the part beginners skip and professionals read first. Knowing the shape of the answer tells you whether this endpoint even holds what you need, which saves the round trip of asking and being disappointed. It also tells you the field names exactly, and field names are case-sensitive and unforgiving.

Examples and the Error List

Every decent reference page carries an example request, and it is almost always a curl command, for the reason Chapter 3 gave: one line states everything with nothing hidden. This example is not decoration. It is the starting point of most real work, copied and then adapted a piece at a time.

Below it, often collapsed, is the error list: the refusals this particular endpoint can produce, each with its status code and a sentence about what triggers it. That list is Chapter 7's syllabus published per endpoint, and reading it before something goes wrong is what turns a future surprise into a future expectation.

A Raid, Demonstrated

Vera has a real question: which stations have fewer than three bikes right now. Watch the ninety seconds. She finds the stations endpoint in the left-hand list and opens it. She scans the parameters table, ignoring the optional rows, and stops at one named max_free_bikes, in the query string, type number, not required. That is the filter, and its presence means the server can do this work instead of her.

She copies the example curl from the page, pastes it into her terminal, and changes exactly one thing: she appends the parameter with the value she wants. Before pressing Enter she glances at the response schema and confirms that name and capacity are both in the answer, because those are the two columns her Thursday report needs.

curl -H "Authorization: Bearer tnd_live_..." \
  https://api.tandem.example/v1/stations

curl -H "Authorization: Bearer tnd_live_..." \
  "https://api.tandem.example/v1/stations?max_free_bikes=3"

The answer comes back holding a handful of stations instead of page after page of them, and the morning's tapping is over. Nothing in that sequence required understanding the API as a whole. It required knowing which five places to look, and in what order.