read-event-type

Reads a single event type, with its schema, if it has one.

Route: QUERY /api/v2/data/read-event-type
Category: data
Authentication: required, with the API token
Answer: a single JSON envelope

The database knows an event type once an event of the type has been written or a schema has been registered for it, and refuses to read one that has neither. Since the answer holds the schema, or null, reading an event type tells you whether it has a schema already, for example before you register one, which can be neither replaced nor removed. To list every event type, use read-event-types.

Request#

The body is a JSON object, with the content type application/json:

Field	Type	Required	Meaning
`type`	string	yes	The event type to read, a reverse domain name such as `io.eventsourcingdb.library.book-acquired`.

To read the event type io.eventsourcingdb.library.book-acquired:

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

Answer#

The answer is a single envelope, rather than a stream, so it has neither heartbeats nor an end 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	When the database knows the event type.
`error`	`code`, `description`, and `details`	When the event type cannot be read, see Errors.

For a database that holds events of the type io.eventsourcingdb.library.book-acquired and a schema for it, 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"
    }
  }
}

Errors#

The route reports these errors as an envelope of the type error:

event-type-missing: The request leaves out the event type, or sends it as an empty string.
event-type-malformed: The event type is not a reverse domain name, such as BookAcquired.
event-type-unknown: The event type has neither events nor a schema, for example because of a typo.
indexes-rebuilding: The indexes that the read needs are still being rebuilt after an upgrade.
restore-in-progress: A restore is running, which refuses reads until it has finished.
file-unreadable: A file of the store that the route 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.

Status Codes#

The server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

400: The content type of the body is not application/json, or the body is missing or no JSON object of the shape above, for example with a field the route does not know, such as eventType, which the v1 API took instead of type, with null as a value, or with a type that is not a string.
401: The API token is missing or wrong.
408: The body did not arrive in time.
413: The body is larger than its limit.
429: Too many requests were sent; the answer says when to try again.
500: The server failed unexpectedly.
503: The server is shutting down. Since the answer is a single envelope, this route reports a shutdown always with this status code, never as server-shutting-down.