Listing Subjects

Listing All Subjects#

The simplest case is listing all subjects for which events have been stored. To do this, send an HTTP request using QUERY to /api/v2/data/read-subjects. Pass the root subject / as subject, and set options.recursive to true, so that the list contains / and every subject below it:

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

If everything worked as expected, the server will respond with HTTP status code 200 OK:

HTTP/1.1 200 OK

The response body is then a stream in NDJSON format, with one subject per line, each as an item of the type subject, followed by an end item, which says that the list is complete. If you've followed the steps in Writing Events, you should see the following three subjects:

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

The list contains /books, although you have never written an event to it: a subject is listed once an event has been written to it or to a subject below it, so every subject with events of its own comes with all of its parents. The subjects are listed in alphabetical order.

Listing a Specific Branch Only#

Sometimes you don't need all subjects – listing just a single branch is sufficient. To do this, set the subject parameter to the desired root:

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

In this case, the list contains /books itself and every subject below it, at any depth, but nothing above it:

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

Without options.recursive, or with it set to false, the list contains only the subject itself, and only if EventSourcingDB knows it. This tells you whether a subject exists: for {"subject": "/books"}, the stream holds /books and the end item, while for a subject that EventSourcingDB doesn't know, such as /books/23, it holds only the end item. If you know the v1 API, which always listed the subjects below as well, see Migrating to the v2 API.