12. Performance
- Measure the cost of parsing and serialization with a reproducible benchmark.
- Know when
orjson(Python) is worth the extra dependency, and when it is not. - Cut the bytes on the wire with HTTP compression (
Accept-Encoding). - Recognize the typical waste: repeated parse/stringify, useless copies,
indentin production.
Theory
Section titled “Theory”JSON parsing is CPU-bound and proportional to the bytes. Rough orders of magnitude on a modern machine: Python’s json module does about 50–100 MB/s, orjson 5–10 times that; V8’s JSON.parse (Node) is in the range of 100–300 MB/s. To find out whether you need to optimize, measure on your own workload: a 10-line benchmark is worth more than any table.
Three rules that weigh more than the library:
- Do not parse twice.
JSON.parse(JSON.stringify(x))as a “deep clone”, or converting string → object → string at every step of a pipeline, is the most common waste. In JS usestructuredClone(x). - Fewer bytes = faster everywhere: network, parsing, memory. Ask only for the fields you need (pagination,
selectin structured queries), and turn on HTTP compression: repetitive JSON compresses 5–10 times. - No
indentin production. Indentation is for humans; between machines it adds 20–40% more bytes for no benefit.
orjson in a nutshell
Section titled “orjson in a nutshell”orjson is a library written in Rust: orjson.loads(bytes|str) -> obj, orjson.dumps(obj) -> bytes (careful: bytes, not str). It natively serializes datetime, dataclass, numpy, UUID; the OPT_INDENT_2 option indents, OPT_SORT_KEYS sorts the keys. It does not support object_hook; default is supported. FastAPI uses it automatically with ORJSONResponse.
curl, explained
Section titled “curl, explained”Let’s measure the bytes with and without compression against the public server (behind Caddy, which compresses).
curl -s -o /dev/null -w '%{size_download} byte, %{time_total}s\n' \https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson
curl -s -o /dev/null -w '%{size_download} byte, %{time_total}s\n' \-H 'Accept-Encoding: gzip' --compressed \https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson
curl -s -D - -o /dev/null -H 'Accept-Encoding: gzip' 'https://corso-api-json.giuseppebosi.com/api/v1/books?limit=100' | grep -i content-encoding- -o /dev/null
- throws the body away: here we only care about the measurements
- -w '…'
- write-out: prints a format with curl variables after the request
- %{size_download}
- bytes actually downloaded (compressed, if compressed)
- %{time_total}
- total request time in seconds
- -H 'Accept-Encoding: gzip'
- a header that tells the server: "I accept a gzip-compressed response" (also
br,zstd) - --compressed
- makes curl decompress the body it receives; without it, curl would save the gzip bytes as they are
- -D -
- dump header: prints the response headers (
-= on screen); with-o /dev/nullthe body is thrown away - grep -i content-encoding
- shows only the header that says how the response is compressed
What you should see:
33891 byte, 0.07s5708 byte, 0.08scontent-encoding: gzipOn the public server the export goes from ~34 KB to ~6 KB. Compression is done jointly by FastAPI (GZipMiddleware, streaming responses included) and the Caddy reverse proxy (which adds zstd and compresses the site pages): you also see it locally with uv run fastapi dev.
Python and TypeScript
Section titled “Python and TypeScript”# pip install httpx orjsonimport json, timeit, httpx, orjson
testo = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson").textrighe = [r for r in testo.splitlines() if r]grande = "[" + ",".join(righe) + "]" # un array JSON da ~34 KBdati = json.loads(grande)N = 200ms = lambda f: timeit.timeit(f, number=N) / N * 1000
print("byte:", len(grande))print("json.loads %.2f ms" % ms(lambda: json.loads(grande)))print("orjson.loads %.2f ms" % ms(lambda: orjson.loads(grande)))print("json.dumps %.2f ms" % ms(lambda: json.dumps(dati)))print("orjson.dumps %.2f ms" % ms(lambda: orjson.dumps(dati)))print(type(orjson.dumps(dati))) # <class 'bytes'> ← attenzioneprint(orjson.dumps({"x": 1.5}, option=orjson.OPT_INDENT_2))Output on the course machine (a modest VPS):
byte: 33885json.loads 0.5 msorjson.loads 0.2 msjson.dumps 0.6 msorjson.dumps 0.1 ms<class 'bytes'>b'{\n "x": 1.5\n}'On 34 KB the difference is half a millisecond: irrelevant. On 340 MB it becomes seconds. Rule of thumb: orjson when you serialize/parse many MB per second (high-traffic APIs, data pipelines); otherwise json is perfectly fine and adds no compiled dependencies.
// node --experimental-strip-types bench.tsconst r = await fetch("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson");const righe = (await r.text()).split("\n").filter(Boolean);const grande = "[" + righe.join(",") + "]";const N = 200;
let t = performance.now();for (let i = 0; i < N; i++) JSON.parse(grande);console.log(`JSON.parse ${((performance.now() - t) / N).toFixed(2)} ms su ${grande.length} byte`);
const dati = JSON.parse(grande);t = performance.now();for (let i = 0; i < N; i++) JSON.stringify(dati);console.log(`JSON.stringify ${((performance.now() - t) / N).toFixed(2)} ms`);
// deep clone: structuredClone batte parse(stringify(x)) ed è corretto con Date, Map, Sett = performance.now();for (let i = 0; i < N; i++) structuredClone(dati);console.log(`structuredClone ${((performance.now() - t) / N).toFixed(2)} ms`);Output on the course machine:
JSON.parse 0.32 ms su 33885 byteJSON.stringify 0.16 msstructuredClone 0.6 msIn JavaScript there is no “orjson”: JSON.parse is already native and optimized. The wins come from rules 1–3 and, for huge files, from the streaming in chapter 11. A real V8 trick: for large configuration objects (>10 KB) included in a bundle, JSON.parse('...') is faster than an object literal, because the JSON parser is simpler than the JS one.
Try it now
Section titled “Try it now”Compare the bytes: a full page versus a projection of only the fields you need.
Response headers
Response headers
Exercise
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?limit=50
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/.
- Repeat the Python benchmark with
grandemultiplied by 100 ("[" + ",".join(righe * 100) + "]", ~3.4 MB). How much does thejson/orjsonratio change? - With curl, measure
%{size_download}of/api/v1/books?limit=100with and without--compressedon the public server. What is the compression ratio?
What to expect
- The ratio stays similar (3–5×) but the absolute values grow to tens of milliseconds: that is where
orjsonstarts to matter. - About 5–7×: JSON with repeated keys (“title”, “price”…) compresses very well. That is why compression should always be on for an API.
Common mistakes
Section titled “Common mistakes”orjson.dumps()returnsbytes:f.write(orjson.dumps(x))on a file opened in text mode fails; open it with"wb"or call.decode().- Benchmarking a single run: the first call pays for caches and the JIT; repeat N times and average (or use
timeit). - Optimizing parsing when the bottleneck is the network (see the warning above).
indent=2left in production code: extra bytes on every response.
Summary
Section titled “Summary”Measure, compress, do not parse twice. orjson is a great lever when the MB per second are many; until then the built-in json is enough. In the next chapter JSON goes into the database: JSON columns, SQL functions and indexes.