Topic 28

When Docs Lie

Docs

Vera reads the reference page for the stations endpoint and writes down the field she needs: the docs say each station arrives with a number called available_bikes. She sends the request. The station comes back, correct in every other way, and the field is called free_bikes. There is no such field as the one the page promised, and for a few minutes she is certain she has misread something. (Where that other name came from is a story Chapter 8 finishes.)

She has not. Documentation is a copy of the truth, and copies drift. Nothing here is broken and nobody has lied on purpose; the page and the server are simply out of step. It is the restaurant menu that still says the soup comes with cream after the kitchen stopped adding it. The bowl in front of you wins the factual argument, and telling the waiter fixes the menu for the next table.

Settling a disagreement between the page and the server

The docs and the response disagree→Send one minimal request

The docs' version differs from your URL→Align them, then look again

Versions match, the wire still differs→Trust the wire, use documented fields

The gap is real and repeatable→Report it with the evidence

Why Documentation Drifts

An API and its documentation are two artifacts that have to be kept in step by people, and people are busy. A team renames a field on the server and the generated page is rebuilt a week later. A hand-written example is written once, is correct that day, and then quietly fossilizes while the endpoint around it moves on. A note about a limit was accurate two years ago.

None of this requires a villain. It is ordinary entropy, and knowing to expect it changes how you react: a mismatch stops being evidence that you are stupid and becomes a normal event with a known procedure. That shift in mood is most of what this page is for.

The One-Command Verdict

When the page and the behavior disagree, send the smallest request that settles it and read what actually comes back. One endpoint, no extra parameters, headers included so you can see the status line. The response is the API as it is; the documentation is the API as promised. Where they differ, the response is the fact.

The minimal request that settles the argument, and the answer it gives

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

HTTP/1.1 200 OK
Content-Type: application/json

{"id": "st_014", "name": "Old Market", "capacity": 24,
 "free_bikes": 9, "status": "active"}

Old Market has nine bikes free, and the field holding that number is spelled the way the server spells it. The argument is over in under a minute, and the gap between page and server is now information Vera owns rather than confusion she is stuck in.

Check the Version First

Before deciding the documentation is wrong, check one thing: which version of the API each side is talking about. Most documentation sites have a version selector somewhere near the top, and it does not always match the version sitting in the URL you are sending to. Reading a page about one version while calling another produces exactly the symptoms of drift and is entirely your own doing.

This is the honest variant of the mismatch, and it is common enough to check first every time. It also raises a question the book has been postponing: why is there a /v1 in the address at all, and what happens when a /v2 appears beside it? Chapter 8 answers that properly, and the answer is more reassuring than it sounds.

Report It Like a Partner

Having confirmed a real gap, send it to the provider. A good drift report is short and contains four things: the endpoint, what the documentation claims, the exact command you sent, and the exact response you got back. Remove the key first and put tnd_live_XXX in its place, as Topic 22 insisted.

Jonas likes these emails, and the reason is worth understanding. A report like that needs no reply asking for details, no guessing, no attempt to reproduce from a vague description. He forwards it, the page gets fixed, and the next person to read it is spared the twenty minutes Vera just spent. That is the moment a reader stops merely consuming an API and starts improving it.

Common Confusions

"The documentation is official, so the API must be misbehaving." The server's behavior is the API. Documentation describes it, with a lag. Start from the page, then let the wire settle it — in that order, and cheaply.
"A mismatch means I misread the page." Sometimes, and checking the version selector against your URL catches most of those. But drift is common enough that expecting it occasionally is calibration rather than cynicism.
"An undocumented field in the response is a secret I should quietly use." It may be a recent addition the page has not caught up with, or something the provider considers internal and may remove without warning. Prefer documented fields for anything that has to keep working, and report the gap.
"Reporting drift is complaining, and providers dislike it." A report with a command and a response in it is the single most useful message a partner can send. Providers fix what they can see, and most of what they cannot see stays broken.

Why It Matters

Verifying with one command ends the documentation-versus-reality argument permanently, and it is the same muscle Chapter 7's debugging checklist exercises when something is actually on fire.
Knowing that versions can skew turns the next chapter's questions into ones you already want answered, starting with why an address carries a version number in the first place.

Knowledge Check

The docs promise a field called available_bikes, and the response contains free_bikes instead. What is going on?

The documentation and the server are out of step
The server is malfunctioning and needs restarting
The request carried the wrong credential entirely
The command line strips fields the browser keeps

What should you check before concluding that a page has drifted?

Whether the same mismatch is still there tomorrow morning
Whether the docs' version matches the version in your URL
Whether other readers have complained about the same page
Whether the sandbox returns the field the documentation names

You have confirmed a genuine gap between the docs and the API. What goes in the report?

A plain description of what looked wrong, written in your own words
The endpoint, the docs' claim, and your command with the real key left in
The endpoint, the docs' claim, your command with the key redacted, and the response
A screenshot of the documentation page with the disputed field circled

You got correct