Skip to content

1. What is JSON

  • Know what JSON is and why it became the universal exchange format.
  • Recognize at a glance the parts of a JSON document: objects, arrays, values.
  • Read a real JSON document returned by an API and understand “what is inside”.

JSON (JavaScript Object Notation) is a text format for representing structured data. It was created in 2001 by Douglas Crockford as a subset of JavaScript object syntax, and it is standardized in RFC 8259 and ECMA-404. Three properties made it ubiquitous:

  1. It is text (UTF-8): you read it in an editor, send it in an HTTP request, save it to a file, store it in a database column.
  2. It is language-independent: every language has a library to turn its own objects into JSON (serialize) and back (deserialize or parse).
  3. It is simple: six value types and two structures. That’s all.

A JSON document is made of:

Element What it looks like Example
Object "key": value pairs inside braces {"id": 1, "title": "Oltre Trieste"}
Array ordered list inside square brackets ["novità", "premio"]
String text inside double quotes "Elena Marchetti"
Number integer or decimal, scientific notation allowed 18.71, 2002, 1e3
Boolean true or false true
null no value null

Objects and arrays nest without limits: an object can contain arrays of objects that contain objects… This is how JSON represents complex structures such as an order with its line items, or a book with its author.

  • HTTP APIs: almost every web service responds in JSON (Content-Type: application/json).
  • Configuration files: package.json, tsconfig.json, VS Code’s settings.json.
  • Databases: PostgreSQL (jsonb), SQLite (json_* functions), MongoDB (BSON documents, a binary JSON).
  • Logs and data: one JSON line per event (JSON Lines, covered in chapter 11).

Let’s ask the test server for the book with id 1. First with curl, explained option by option:

terminal
curl -s https://corso-api-json.giuseppebosi.com/api/v1/books/1
curl
makes an HTTP request and prints the response in the terminal
-s
silent: hides the progress bar, so you only see the response
https://corso-api-json.giuseppebosi.com
scheme (https) and host of the server
/api/v1/books/1
the path: resource books, item with id 1. No method given = GET

Response (reformatted with line breaks so you can read it; over the wire it travels on a single line):

{
"id": 1,
"title": "Il silenzio di Ustica",
"isbn": "978-88-81482-001-1",
"author_id": 19,
"category_id": 2,
"price": 18.71,
"pages": 120,
"published_year": 2002,
"language": "it",
"in_stock": true,
"attributes": {
"format": "brossura",
"cover": "morbida",
"awards": [],
"dimensions_cm": { "w": 15, "h": 19 },
"ebook": false
},
"created_at": "2025-06-01T00:00:00Z",
"reviews_count": 0,
"avg_rating": null
}

Let’s read it with the mental rule:

  • The opening brace: it is an object, the book.
  • "id": 1 → number. "title": "…" → string. "in_stock": true → boolean. "avg_rating": null → no value (the book has no reviews yet).
  • "attributes": { … } → an object inside the object: it in turn contains "awards": [] (an empty array) and "dimensions_cm": {"w": 15, "h": 19} (another object).
  • "created_at": "2025-06-01T00:00:00Z" → careful: this is a string. JSON has no “date” type: we will come back to this in chapter 3.
  • "author_id": 19 → a number that points to another resource (author 19). This is how JSON, and databases, express relations: you will go deeper in Section 2.

Now run it yourself, from the browser:

GET/api/v1/books/1— the book with id 1

The next chapters go into detail; for now, here is how little it takes to download that JSON and turn it into an object of your language.

# pip install httpx
import httpx
r = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/books/1")
libro = r.json() # da testo JSON a dict Python
print(type(libro)) # <class 'dict'>
print(libro["title"]) # Il silenzio di Ustica
print(libro["attributes"]["dimensions_cm"]["h"]) # 19

What you should see:

<class 'dict'>
Il silenzio di Ustica
19

Try it online, nothing to install:

Open the notebook in Google Colab Open the TypeScript project in StackBlitz

The GET request straight in your browser: https://corso-api-json.giuseppebosi.com/api/v1/books/1

Python on Google Colab (a free Google account is needed to run the cells); TypeScript on StackBlitz (it opens and starts by itself in the browser). If the practice API is switched off, turn it on from /en/api-attiva/.

Download https://corso-api-json.giuseppebosi.com/api/v1/orders/1 (with curl or with the button below) and answer:

  1. How many levels of nesting does shipping_address have?
  2. Is items an object or an array? How many elements does it have?
  3. Which field links each order line to a book?
GET/api/v1/orders/1— order 1 with its line items
Solution
  1. One: shipping_address is an object with four strings (street, city, zip, country).
  2. An array ([…]) of objects: one line per book ordered (the number depends on the order: in order 1 it is 1).
  3. book_id: it is a foreign key to books.id. In Section 2, chapter 5, you will learn to “follow” it with ?expand=items.book.
  • Confusing JSON with a JavaScript object. JSON is text; the object is what you get after parsing. '{"a":1}' (string) ≠ {a: 1} (object).
  • Single quotes. {'a': 1} is not valid JSON: strings and keys go inside double quotes.
  • Trailing comma. {"a": 1,} is not valid. Many editors tolerate it, parsers do not.

JSON is text, with six types and two nestable structures. An API returns it, your language turns it into native objects, and back. The next chapter covers the complete syntax, rule by rule.