Basic

JSON as the payload

The body was a blob of text and I needed the fields inside it. JSON is the format that turns that blob into named values you can reach, and it is the default for modern APIs.

What you will see

About 2 min of reading

Try It

Parse a JSON response and reach a field, then build one to send.

Fetch a JSON body and parse it, then print one field.

import json import urllib.request text = urllib.request.urlopen('https://api.example/users').read() data = json.loads(text) print(data[0]['id'])

Before you run it, say out loud what it will print. Then open the answer.

What it prints

Build a payload from a value to send back.

import json payload = json.dumps({'name': 'Grace'}) print(payload)

Before you run it, say out loud what it will print. Then open the answer.

What it prints

{"name": "Grace"}

A number that arrived quoted is a string, not a number. Check the type after parsing.

import json v = json.loads('{"id": "7"}') print(type(v['id']))

Before you run it, say out loud what it will print. Then open the answer.

What it prints

A quoted number in JSON is a string. If your code adds it, you get a type error or a concatenation. Check types after the parse, do not assume the wire kept them.

Put it in order

Before you write anything, put these lines back in the right order. Click a line to move it up one step. This support step is easier than writing code from scratch, and it is here to make the last example stick.

Data Flow

The body is JSON text, a parse turns it into a value with named fields, and you reach those fields; a build turns a value back into text to send.

1 Body is JSON text

↓

2 Parse turns it into a value

↓

3 Reach fields by key

↓

4 Build turns a value back to text

Line by line

Read the first example one line at a time. A line that prints shows what appears on screen; the rest set things up quietly.

import json sets nothing on screen

import urllib.request sets nothing on screen

text = urllib.request.urlopen('https://api.example/users').read() sets nothing on screen

data = json.loads(text) sets nothing on screen

print(data[0]['id']) 1

Why this works

JSON is a wire format

JSON is text that stands in for a value. On the wire it is bytes, in your program it is a dict or object. The parse (loads) and the build (dumps) are the two directions. Everything else about an API is moving these values around.

Keys are strings

In JSON every key is a quoted string and every value has a type. A number is not quoted, a string is. This is why a field that should be a number arrives as a string when someone quotes it, and why you check types after parsing.

Examples

The shape

{"name": "Ada", "id": 1, "tags": ["a", "b"]}

JSON is objects in braces, arrays in brackets, keys in quotes. It maps directly to a value in your language once parsed.

Parse it

import json
body = json.loads(text)
print(body["name"])

json.loads turns the text into a dict. Then you reach fields by key. The parse is the seam between bytes and values.

Build it

payload = json.dumps({"name": "Ada"})

json.dumps turns a value back into JSON text to send. The two functions are the whole bridge between your data and the wire.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Headers describe the body

Previous Lesson

Headers describe the body

Next Lesson

Asking in the URL

Asking in the URL →