Skip to content

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, indent in production.

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:

  1. 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 use structuredClone(x).
  2. Fewer bytes = faster everywhere: network, parsing, memory. Ask only for the fields you need (pagination, select in structured queries), and turn on HTTP compression: repetitive JSON compresses 5–10 times.
  3. No indent in production. Indentation is for humans; between machines it adds 20–40% more bytes for no benefit.

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.

Let’s measure the bytes with and without compression against the public server (behind Caddy, which compresses).

terminal
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/null the 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.07s
5708 byte, 0.08s
content-encoding: gzip

On 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.

# pip install httpx orjson
import json, timeit, httpx, orjson
testo = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson").text
righe = [r for r in testo.splitlines() if r]
grande = "[" + ",".join(righe) + "]" # un array JSON da ~34 KB
dati = json.loads(grande)
N = 200
ms = 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'> ← attenzione
print(orjson.dumps({"x": 1.5}, option=orjson.OPT_INDENT_2))

Output on the course machine (a modest VPS):

byte: 33885
json.loads 0.5 ms
orjson.loads 0.2 ms
json.dumps 0.6 ms
orjson.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.

Compare the bytes: a full page versus a projection of only the fields you need.

GET/api/v1/books?limit=50— 50 full books
POST/api/v1/query— the same 50 books, only three fields

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?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/.

  1. Repeat the Python benchmark with grande multiplied by 100 ("[" + ",".join(righe * 100) + "]", ~3.4 MB). How much does the json/orjson ratio change?
  2. With curl, measure %{size_download} of /api/v1/books?limit=100 with and without --compressed on the public server. What is the compression ratio?
What to expect
  1. The ratio stays similar (3–5×) but the absolute values grow to tens of milliseconds: that is where orjson starts to matter.
  2. About 5–7×: JSON with repeated keys (“title”, “price”…) compresses very well. That is why compression should always be on for an API.
  • orjson.dumps() returns bytes: 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=2 left in production code: extra bytes on every response.

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.