Listing Subjects

This guide shows how to list the existing subjects from EventSourcingDB using its HTTP API. You'll learn how to list either all or a desired subset of the existing 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 POST to the /api/v1/read-subjects endpoint:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer <API_TOKEN>" \
  -H "content-type: application/json" \
  -d '{"baseSubject": "/"}' \
  http://localhost:3000/api/v1/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 will then contain a list of all existing subjects. If you've followed the steps in Writing Events, you should see the following three subjects:

{
  "type": "subject",
  "payload": {
    "subject": "/"
  }
}
{
  "type": "subject",
  "payload": {
    "subject": "/books"
  }
}
{
  "type": "subject",
  "payload": {
    "subject": "/books/42"
  }
}

In reality, the output will look slightly different – the subjects are returned as compact NDJSON, with each subject occupying a single line.

Listing a Specific Branch Only

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

curl \
  -i \
  -X POST \
  -H "authorization: Bearer <API_TOKEN>" \
  -H "content-type: application/json" \
  -d '{"baseSubject": "/books"}' \
  http://localhost:3000/api/v1/read-subjects

In this case, only the subjects located directly below /books will be returned.