APIs from zero
JSON
Most APIs send and receive data as JSON. How to read it, the six kinds of value, and how to point at one value inside a big answer with a path.
JSON (JavaScript Object Notation, said "jay-son") is the format most APIs use for data, in both directions. It's plain text that both people and programs can read:
{
"id": "A-1001",
"status": "paid",
"total": 45.5,
"giftWrap": false,
"note": null,
"customer": { "name": "Ann", "city": "Pune" },
"items": [
{ "sku": "LAMP-1", "quantity": 1, "price": 39 },
{ "sku": "NOTE-2", "quantity": 2, "price": 3.25 }
]
}
The six kinds of value
| Kind | Looks like | Notes |
|---|---|---|
| string (text) | "paid", "A-1001" | Always in double quotes |
| number | 45.5, 2, -3, 1e6 | No quotes. One kind for whole and decimal numbers |
| boolean | true, false | Lowercase, no quotes |
| null | null | "No value" — different from an empty string "" or 0 |
| object | { "name": "Ann", "city": "Pune" } | Named values ("fields", "keys", "properties") in { } |
| array (list) | [1, 2, 3], [{ … }, { … }] | Values in order, in [ ] |
Objects and arrays nest: an order object has an items array of item objects. That's how one answer describes a whole order.
Small rules that trip people up
- Names are in double quotes too:
{ "status": "paid" }, not{ status: "paid" }and not{ 'status': 'paid' }. - No comma after the last item:
[1, 2, 3], not[1, 2, 3,]. - No comments.
"45"(a string) and45(a number) are different. An API that suddenly sends prices as strings can break every app that does arithmetic with them — a classic thing for tests to catch.- A missing field and a field set to
nullare different too:{ "note": null }says "there's no note";{}doesn't mention notes at all.
Pointing at one value: paths
Answers can be long. To talk about one value inside — in a test, or to save it for the next request — you write a path from the top:
| Path | In the order above | Value |
|---|---|---|
status | the order's status | "paid" |
customer.name | the customer, then their name | "Ann" |
items[0].sku | the items, the first one (counting from 0), its sku | "LAMP-1" |
items[1].quantity | the second item's quantity | 2 |
items | the whole list | the array |
A dot goes into an object; [n] picks the n-th entry of an array, starting at 0. Many tools write a $ for "the top": $.items[0].sku is the same path. (This style comes from JSONPath, which has more tricks, like $..sku for every sku anywhere — handy, but the simple form covers most needs.)
JSON in requests
When you send JSON, say so with the header Content-Type: application/json. Most tools add it when you choose a JSON body. If the server answers 400 Bad Request to a POST, invalid JSON is the first suspect — a missing quote or a trailing comma.
JSON's relatives
You'll occasionally meet XML (older APIs and SOAP: <order><status>paid</status></order>), form encoding (status=paid&total=45.5, for sign-ins and HTML forms), and YAML (indented text, used for configuration and API descriptions like OpenAPI files). They all describe data; JSON is simply the most common for APIs today.
Key takeaways
- JSON has six kinds of value: string, number, boolean, null, object, array — and
"45"is not45. - A path points at one value:
customer.name,items[0].sku— arrays count from 0. - Send JSON with
Content-Type: application/json; a400to a POST often means broken JSON.
In the app: Kinds of checks · The body