read-subjects

Lists a subject, or a subject together with every subject below it.

Route: QUERY /api/v2/data/read-subjects
Category: data
Authentication: required, with the API token
Answer: a stream of NDJSON

A subject is listed when it holds events itself, or a subject below it does. So /books is listed once /books/42 holds an event, even though no event was written to /books, while a subject without any event at or below it is not listed at all. The tutorial Listing Subjects walks through it step by step.

Request#

The body is a JSON object, with the content type application/json:

Field	Type	Required	Meaning
`subject`	string	yes	The subject to list, a slash-separated path such as `/books`.
`options.recursive`	boolean	no	Whether to list every subject below the given one as well. Defaults to `false`, which lists the given subject alone.

To list /books and every subject below it:

curl \
  -X QUERY \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d '{"subject":"/books","options":{"recursive":true}}' \
  http://localhost:3000/api/v2/data/read-subjects

Answer#

The answer is a stream of items, one per line. Each subject is a subject item:

Type	Data	When
`subject`	`subject`, the subject as a string	For every subject that the listing finds.
`error`	`code`, `description`, and `details`	When the listing cannot go on, see Errors.
`heartbeat`	empty	While nothing else is sent for a while, to keep the connection alive.
`end`	empty	Once, as the last item, when the stream ends cleanly.

Heartbeats and the end item work as on every stream of the API, see Streams. A subject that holds no event, neither itself nor below it, is answered with the end item alone.

For a database that holds events in /books/42, /books/42/copies/1, and /books/43, the request above is answered with:

{"type":"subject","data":{"subject":"/books"}}
{"type":"subject","data":{"subject":"/books/42"}}
{"type":"subject","data":{"subject":"/books/42/copies"}}
{"type":"subject","data":{"subject":"/books/42/copies/1"}}
{"type":"subject","data":{"subject":"/books/43"}}
{"type":"end","data":{}}

Errors#

The listing reports these errors as an error item, followed by the end item:

subject-missing: The request leaves out the subject, or sends it as an empty string.
subject-malformed: The subject is not a valid subject, such as books without its leading slash.
subject-too-long: The subject is longer than 1,024 characters.
subject-too-deep: The subject has more than 32 segments.
indexes-rebuilding: The indexes that the listing needs are still being rebuilt after an upgrade.
restore-in-progress: A restore is running, which refuses reads until it has finished.
file-unreadable: A file of the store that the listing needs is damaged, such as an events file whose checksum no longer matches.
store-failed: The store refuses reads for good, after a restore that could not empty it again.
server-shutting-down: The server began to shut down while a recursive listing was running. Before the stream begins, the server answers with 503 instead.

Status Codes#

Before the stream begins, the server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

400: The content type of the body is not application/json, or the body is missing or no JSON object of the shape above, for example with a field the route does not know, such as recursive outside of options, or with null as a value.
401: The API token is missing or wrong.
408: The body did not arrive in time.
413: The body is larger than its limit.
429: Too many requests were sent, or the client already holds 256 open streams, see Rate Limiting; the answer says when to try again.
500: The server failed unexpectedly before the stream began. Once it has begun, the stream breaks off without its end item instead.
503: The server is shutting down.