Listing Event Types

This guide shows how to list the existing event types from EventSourcingDB using its HTTP API. You'll learn how to retrieve all event types that have been used so far.

Listing All Event Types#

To retrieve the list of all known event types, send an HTTP request using QUERY to /api/v2/data/read-event-types. The route takes no parameters, so the request has no body:

curl \
  -i \
  -X QUERY \
  -H "authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v2/data/read-event-types

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 event type per line, each as an item of the type eventType, followed by an end item, which says that the list is complete. If you've followed the steps in Writing Events and Registering Event Schemas, you should see the following event types:

{"type":"eventType","data":{"type":"io.eventsourcingdb.library.book-acquired","hasEvents":true,"schema":{"additionalProperties":false,"properties":{"author":{"type":"string"},"isbn":{"type":"string"},"title":{"type":"string"}},"required":["title","author","isbn"],"type":"object"}}}
{"type":"eventType","data":{"type":"io.eventsourcingdb.library.book-borrowed","hasEvents":true,"schema":null}}
{"type":"end","data":{}}

Each event type comes with three fields: type names it, hasEvents says whether events of that type exist, and schema holds its schema. If you know the v1 API, see Migrating to the v2 API for how these fields differ from it.

Schemas Included

If you have previously registered a schema for an event type, schema holds it, as it does for book-acquired above. Otherwise, schema is null.

A Word on Phantom Event Types#

You may have noticed that the response not only includes the event types themselves, but also indicates with hasEvents whether events of each type exist. An event type that has none is called a phantom.

This raises the question: when is an event type considered a phantom?

An event type is a phantom, with hasEvents set to false, if EventSourcingDB knows already about this event type, although no events of that type have been written yet (e.g., because a JSON schema was registered for the given event type).
An event type is not a phantom, with hasEvents set to true, if at least one event of that type exists.

Listing a Specific Event Type#

In some cases, you may want to retrieve detailed information about a specific event type. To do so, send an HTTP request using QUERY to /api/v2/data/read-event-type and include the event type you are interested in as type in the request body:

curl \
  -i \
  -X QUERY \
  -H "authorization: Bearer <API_TOKEN>" \
  -H "content-type: application/json" \
  -d '{ "type": "io.eventsourcingdb.library.book-acquired" }' \
  http://localhost:3000/api/v2/data/read-event-type

If everything worked as expected, the server will respond with HTTP status code 200 OK and return a single JSON object rather than a stream: an envelope of the type eventType, whose data holds all details about the event type:

{
  "type": "eventType",
  "data": {
    "type": "io.eventsourcingdb.library.book-acquired",
    "hasEvents": true,
    "schema": {
      "additionalProperties": false,
      "properties": {
        "author": { "type": "string" },
        "isbn": { "type": "string" },
        "title": { "type": "string" }
      },
      "required": ["title", "author", "isbn"],
      "type": "object"
    }
  }
}

If EventSourcingDB doesn't know the event type, because it has neither events nor a schema, the response is an error with the code event-type-unknown instead, still with the status 200 OK:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/event-type-unknown",
    "description": "event type is unknown: it has neither events nor a registered schema",
    "details": {
      "value": "io.eventsourcingdb.library.book-returned"
    }
  }
}