read-event-types

Lists every event type that the database knows, each with its schema, if it has one.

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

The database knows an event type once an event of the type has been written or a schema has been registered for it. So an event type with a schema but without any events is listed as well, with hasEvents set to false. The listing shows the event types as of the moment it starts. The tutorial Listing Event Types walks through it step by step, and read-event-type reads a single event type.

Request#

The route takes no body, and ignores one that is sent:

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

Answer#

The answer is a stream of items, one per line. Each event type is an eventType item:

Type	Data	When
`eventType`	`type`, the event type; `hasEvents`, whether events of the type have been written; and `schema`, its schema, or `null` if it has none	For every event type that the database knows.
`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 database that knows no event type answers with the end item alone.

For a database that holds events of the types io.eventsourcingdb.library.book-acquired, which has a schema, and io.eventsourcingdb.library.book-borrowed, which has none, and a schema for io.eventsourcingdb.library.book-returned, which has no events yet, the request above is answered with:

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

Errors#

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

indexes-rebuilding: The indexes that the listing needs are still being rebuilt after an upgrade.
restore-in-progress: A restore is running as the listing starts, or begins while it runs, 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 the 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:

401: The API token is missing or wrong.
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.