read the data shapes

The two data structures every API response is made of

Open the JSON tab in your browser's DevTools next time you load a website. Or run curl https://api.github.com/repos/anthropics/claude-cookbook in your terminal. The response is a tree of two things: lists (ordered collections in [ ]) and dicts (key-value maps in { }). Sometimes nested fifteen levels deep, but always those two structures.

Every API you'll ever consume is a list-and-dict tree. Every JSON file you parse, every database row you load, every LLM response object — list-and-dict, list-and-dict, list-and-dict. And every time you say "for each user, do X" to your AI assistant, it writes a loop that walks one of those trees. This chapter is about reading the shape on sight, walking it without getting lost, and spotting the exact places AI gets the walk wrong.

The mental model

Lists are ordered. Items are accessed by position: users[0] is the first user, users[-1] is the last. Use a list when "first one I added" and "in the order I added them" matter.

Dicts are key-addressed. Items are accessed by name: user["email"] is the email field, user["preferences"]["theme"] is the theme inside the preferences dict. Use a dict when you have named fields and you want to look one up directly.

Real data is both. A JSON response from any API is typically a dict at the top level, with a list of items somewhere inside, where each item is itself a dict with named fields. The bones of every API.

response = {
    "page": 1,
    "items": [
        {"id": 42, "title": "first thing"},
        {"id": 43, "title": "second thing"},
    ],
}
print(response["items"][1]["title"])  # "second thing"

That access path — response["items"][1]["title"] — is a core pattern in Python data work. Read it left-to-right: dict-key, list-index, dict-key. Once that pattern reads cleanly to you, every API call you'll touch is approachable.

What this chapter covers in three lessons

Lesson 1: The shapes AI dumps on you. Lists and dicts side by side, indexing from zero, and the access paths through nested JSON — plus the two crashes AI ships most: KeyError from a key that isn't there, and TypeError from treating a list like a dict.

Lesson 2: Walking the shape. The for loop — what AI writes every time you say for each — and the reading habit that makes nested-walk code legible: at the top of every loop body, ask what kind of thing is the loop variable right now? Includes the accumulator pattern and the dict-loop mistake AI keeps making.

Lesson 3: Comprehensions and the wrong-layer bug. Python's most-loved one-liner: [x * 2 for x in numbers]. AI uses these constantly because they're idiomatic — and when it gets one wrong, it's usually because it looped the wrong layer of the tree. Reading comprehensions well is half of reading modern Python.

What AI specifically gets wrong with data shapes

Three patterns:

1. KeyError from assuming a field exists. API returns vary. AI writes data["items"] without checking, and the request that returned data["error"] instead crashes. Lesson 1 drills reading the actual shape before trusting the keys.

2. Looping the wrong layer. AI writes for team in org: when it meant for team in org["teams"]:. The first walks the keys of the outer dict, not the list of teams — and it often doesn't crash, it just hands you strings instead of dicts. Lessons 2 and 3 both drill this.

3. A comprehension that filters or replaces when you wanted the other one. An if at the end of a comprehension drops items; an if/else inside the expression replaces them. AI mixes these up, and the output silently fills with placeholder junk. Lesson 3 covers it.

What you'll be able to do at the end

Three lessons, 24 steps. By the end you'll be able to:

• Read any JSON response (or Python dict/list nesting) and traverse to the value you want without getting lost.
• Read any for loop over data and predict its output without running it.
• Read the comprehensions AI ships most often, and spot the wrong-layer bug in them.
• Use your own AI assistant as a syntax reference — with a verification habit that catches it when it's wrong.

This is the chapter that makes API work approachable. The later chapters on HTTP and APIs, LLM APIs, and structured output all assume you can read nested data. The more this chapter clicks, the easier those land.

Press Start chapter below.