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”.
Theory
Section titled “Theory”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:
- 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.
- It is language-independent: every language has a library to turn its own objects into JSON (serialize) and back (deserialize or parse).
- 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.
Where you meet it
Section titled “Where you meet it”- HTTP APIs: almost every web service responds in JSON (
Content-Type: application/json). - Configuration files:
package.json,tsconfig.json, VS Code’ssettings.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).
A real JSON document, read together
Section titled “A real JSON document, read together”Let’s ask the test server for the book with id 1. First with curl, explained option by option:
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 id1. 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:
Response headers
The same in Python and TypeScript
Section titled “The same in Python and TypeScript”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 httpximport httpx
r = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/books/1")libro = r.json() # da testo JSON a dict Pythonprint(type(libro)) # <class 'dict'>print(libro["title"]) # Il silenzio di Usticaprint(libro["attributes"]["dimensions_cm"]["h"]) # 19What you should see:
<class 'dict'>Il silenzio di Ustica19// node --experimental-strip-types libro.tsconst r = await fetch("https://corso-api-json.giuseppebosi.com/api/v1/books/1");const libro = await r.json(); // da testo JSON a oggetto JavaScriptconsole.log(typeof libro); // objectconsole.log(libro.title); // Il silenzio di Usticaconsole.log(libro.attributes.dimensions_cm.h); // 19What you should see:
objectIl silenzio di Ustica19Exercise
Section titled “Exercise”Try it online, nothing to install:
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:
- How many levels of nesting does
shipping_addresshave? - Is
itemsan object or an array? How many elements does it have? - Which field links each order line to a book?
Response headers
Solution
- One:
shipping_addressis an object with four strings (street,city,zip,country). - An array (
[…]) of objects: one line per book ordered (the number depends on the order: in order 1 it is 1). book_id: it is a foreign key tobooks.id. In Section 2, chapter 5, you will learn to “follow” it with?expand=items.book.
Common mistakes
Section titled “Common mistakes”- 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.
Summary
Section titled “Summary”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.