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

KindLooks likeNotes
string (text)"paid", "A-1001"Always in double quotes
number45.5, 2, -3, 1e6No quotes. One kind for whole and decimal numbers
booleantrue, falseLowercase, no quotes
nullnull"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) and 45 (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 null are 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:

PathIn the order aboveValue
statusthe order's status"paid"
customer.namethe customer, then their name"Ann"
items[0].skuthe items, the first one (counting from 0), its sku"LAMP-1"
items[1].quantitythe second item's quantity2
itemsthe whole listthe 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 not 45.
  • A path points at one value: customer.name, items[0].sku — arrays count from 0.
  • Send JSON with Content-Type: application/json; a 400 to a POST often means broken JSON.

In the app: Kinds of checks · The body

Next: Signing in: authentication

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.