APIs for Beginners
by Sergey Okinchuk

Chapter Four · The Answers, Fluently

Reading JSON

The braces and brackets you have been reading on intuition, replaced with actual rules — and the rules are six kinds of value, taught honestly in one page. Then the craft: paths to any buried field, the four-step strategy that shrinks a fifty-station response to thirty seconds, the zero-null-missing distinction that keeps reports truthful, and the field guide to XML, CSV, and every other costume the same facts wear. After this chapter, no answer any API sends you will read as foreign.

Every answer in this book so far arrived dressed in braces and brackets, and you have been reading it on intuition. This chapter replaces intuition with the actual rules — and the rules turn out to be almost embarrassingly small. JSON's entire grammar is six kinds of value: objects, arrays, and four kinds of leaf. One page teaches all of it, honestly, with nothing held back for an advanced course.

The rest of the chapter is craft. Nesting, and the paths that name any buried field. The four-step strategy that takes a fifty-station response down to the thirty seconds it deserves — pretty-print, find the shape, read one element, let the rest exist. And the field guide to everything that is not JSON: XML still running the banks, CSV that spreadsheets open directly, and the Content-Type habit that turns "garbled garbage" into "correct answer, different clothes."

One specimen, fully annotated
{ } — an object
labelled facts, found by name: "capacity": 24
[ ] — an array
an ordered list, found by position: fifty stations, one per entry
The four leaves
"strings" in quotes · bare numbers · true / false · null, the deliberate nothing

Topics in This Chapter

Topic 16
The Whole Grammar in One Page
JSON is not code — it is data written down, and its entire grammar is six kinds of value. Objects, arrays, the four leaves, and the three-way distinction (zero, null, missing) that keeps reports honest.
Data
Topic 17
Nesting: Objects Inside Objects
Objects inside objects, like folders inside folders — and every buried field has exactly one path: stations[2].location.lat. Why data nests, how positions count from zero, and why docs' schemas are this skill applied in advance.
Data
Topic 18
Reading a Big Response Without Drowning
Nobody reads the phone book. Pretty-print, find the shape, read one element well, let the rest exist — plus the envelope pattern whose page and total_pages fields quietly set up all of Chapter 8.
Data
Topic 19
Not Everything Is JSON
The Thursday the export handed Vera CSV instead — and the label said so all along. XML still running the banks, CSV that spreadsheets love, choosing formats with Accept, and the check-the-label habit.
Data