Learn / Tutorials / First Steps with EventSourcingDB / Listing Subjects
Step 7 of 8

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.