Not Everything Is JSON
One Thursday, Tandem's ride-export endpoint hands Vera a block of text that is definitely not JSON: lines of values separated by commas, one ride per line. Her first instinct — something broke — is wrong, and the label on the response says so. The export endpoint speaks CSV, the docs said it would, and it is exactly what her spreadsheet wants. APIs speak more than one format, and this page is the field guide.
The one habit that resolves every "garbled response" moment: read the label before judging the body. Content-Type — the header you met in Chapter 2 — names what actually arrived. Check it first, and most format surprises turn out to be correct answers in unexpected clothes.
st_014,Old Market,9
The Formats You Will Actually Meet
Four cover nearly everything. JSON — this era's default, the last three pages. XML — the previous era's default: the same facts wrapped in angle-bracket tags, wordier but no deeper. It is not a relic; banks, insurers, airlines, and government systems speak it daily, and Chapter 10 visits the ceremony built around it. CSV — comma-separated values: a header line naming the columns, then one line per thing. No nesting, pure table — which is why export endpoints love it and spreadsheets open it directly. And plain text or binary — log output, images, PDFs: not everything is structured data.
Same Facts, Different Clothes
Look at the figure above: one station, three costumes. The information is identical — id, name, bike count — and that is the point worth internalizing. Formats are packaging, not meaning. Your Chapter 4 skills carry across with minor costume changes: XML's tags are labels like JSON's keys; CSV's header line plays the role of the labels for every row under it. Learn to see the facts through the clothes, and no format will read as foreign again.
Sometimes You Choose the Format
Some endpoints serve one format, full stop. Others let you pick, and the docs say how: either an Accept header in the request — Chapter 2's "what I would like back," now doing real work — or a parameter like ?format=csv — and a few APIs document a filename-style suffix such as .csv on the path; what never works is inventing one the docs do not list. Tandem's ride export defaults to JSON and offers CSV precisely because reports live in spreadsheets. Asking for the right format at the source beats converting afterwards — one more case of letting the server do the work.
- "A non-JSON response means something is misconfigured." CSV from an export endpoint is the documented, intended answer. Format follows purpose — check Content-Type, then the docs, before declaring anything broken.
- "XML is obsolete trivia I can skip." Your bank very likely speaks it today. Recognizing it — same facts, angle-bracket clothes — is practical literacy, and Chapter 10 gives its world a fair page.
- "The file extension tells me the format." API responses have no filename. Content-Type is the only honest label, and it rides on every response that carries a body.
- "CSV is a lesser format for lesser data." CSV is the right format for tables — which is why exports and spreadsheets meet there. Formats are not ranked; they are matched to jobs.
- The check-the-label habit converts a whole class of "the API returned garbage" panics into "ah — CSV, even better for my spreadsheet." Thirty seconds, no support ticket.
- Knowing formats are costumes keeps you calm in mixed-format workplaces — which is all of them. The facts underneath are the same facts, and you can already read facts.
Knowledge Check
A response looks like garbled text. What is the first check?
- Send the request again in case the response was corrupted in transit
- Read the Content-Type header to learn what actually arrived
- Contact the provider's support with a screenshot of the strange text
- Check the status code, which indicates the format of the body
Why does Tandem's ride export offer CSV at all, when the rest of the API speaks JSON?
- To support very old office software that cannot understand JSON at all
- Because CSV is compressed and saves the server bandwidth on big exports
- Because exports are tables headed for spreadsheets, and spreadsheets open CSV directly
- Because CSV can represent nested data more clearly than JSON
How do you request a specific format, when an endpoint offers several?
- With an Accept header or a documented parameter like ?format=csv
- By adding .csv to the end of the path, which every API accepts
- By setting Content-Type on your request to the format you want back
- You cannot — the server and client negotiate the format automatically
You got correct