The URL, Taken Apart

Vera has typed web addresses for twenty years without once actually reading one. Fair enough — as a user, she never needed to. But every request in this book starts by writing an address, and the addresses in API documentation are meant to be read, edited, and understood part by part. So this page takes one apart: https://api.tandem.example/v1/stations?status=active.

That string is a URL — a web address — and it is not one opaque blob. It is four parts with four separate jobs, like a postal address read top to bottom: country, city, street, apartment. Each part narrows down where the request goes and what it asks. Learn the four rooms once, and every address in every API's documentation becomes legible.

The Scheme: How to Talk

The letters before :// announce the language and the security of the conversation. HTTP is the language of the web — the set of rules for how requests and responses are written, and the subject of this whole chapter. The s in https means three protections travel together: the conversation is encrypted so nobody along the road can read it, it cannot be tampered with unnoticed, and your side has checked it really is talking to the server named in the address — which is what will make it safe to hand over a key in Chapter 5. The little icon next to the address — a padlock in some browsers, a settings glyph in others — means exactly this. (The machinery underneath has a name, TLS, which you will meet again in passing.)

One paragraph of honesty about depth: how the encryption works, and everything under it — cables, packets, the machinery of the internet — is its own subject, and this catalogue covers it in the Networking Deep Dive. For this book, the working rule is enough: https means private in transit, and serious APIs use it always. It matters most in Chapter 5, when your requests start carrying a key.

The Host: Which Building

The next part, api.tandem.example, names the server — which building on the internet this request travels to. Note the api prefix at the front: it is a convention, a separate entrance from the www door where the human-facing website lives. Same organization, two doors — exactly the two doors from Chapter 1, given addresses.

The Path: Which Room

After the host comes /v1/stations — the path, which walks you through the building to the right room. Tandem's path starts with a version, v1, a promise-keeping device that gets its own page in Chapter 8. Then the resource: stations. A verb and a path together — GET /v1/stations — are what documentation calls an endpoint: one door at the counter, with one thing behind it. A single station has its own room: /v1/stations/st_014 is Old Market specifically. The paths an API offers are its floor plan, and the documentation is the directory in the lobby — Chapter 6 teaches you to read it.

The Query: the Details of Your Ask

Everything after the ? is the query string — the fine print of your ask, written (by near-universal convention) as name=value pairs. status=active means "only the active stations, please." It is not a different room; it is instructions to the clerk in this one. Multiple instructions chain with an &, and there is a whole craft to them that gets its own page in Chapter 3. For now, just read them as what they are: your ask, made precise.