streaming only.Expand description
JSON Lines: one resource per line, streamed as rows arrive.
A JSON:API collection document is a single value: the closing bracket cannot be written until the last row is known, so the whole page is held in memory and the client waits for all of it. That is the right trade for a page of twenty-five. It is the wrong one for an export of a million rows, where the document never fits in memory on either end.
JSONL inverts it. Each line is a complete resource object, so the server writes a row and forgets it, and the client parses a row and acts on it — neither holds more than one at a time, and the first row arrives in milliseconds rather than after the last one is found.
{"type":"todo","id":"t_1","attributes":{"message":"buy milk"}}
{"type":"todo","id":"t_2","attributes":{"message":"write docs"}}§Asking for it
Accept: application/jsonl on the ordinary collection URL. There is no
second route: the collection is one resource, and how it is rendered is
what Accept is for — so a cache keyed on Vary: Accept already knows
these are two representations of one thing.
Anything else — including no Accept at all — gets the JSON:API document,
so this cannot change what an existing client receives.
§What is lost
A JSONL response carries no links, no meta and no included: there is
no document to hang them on. It is a row stream, not a document, and a
client that needs pagination links should ask for the document instead.
Errors are the exception — see ERROR_LINE.
Constants§
- ERROR_
LINE - The shape of a failure that happens after the first line is sent.
- LINE_
MEMBER - The member carrying an input line’s 1-based number on a result line.
- MEDIA_
TYPE - The media type:
application/jsonl. - MEDIA_
TYPE_ NDJSON - The other spelling clients use for the same thing.
Functions§
- is_
jsonl_ request - Whether a request body is JSONL, from its
Content-Type. - wants_
jsonl - Whether an
Acceptheader asks for JSONL.