# 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](/docs/eventsourcingdb/event-types)** 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](/docs/eventsourcingdb/api/register-event-schema)**, which can be neither replaced nor removed. To list every event type, use **[read-event-types](/docs/eventsourcingdb/api/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`:

```shell
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](#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:

```json
{
  "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`](/docs/eventsourcingdb/errors/event-type-missing)**: The request leaves out the event type, or sends it as an empty string.
- **[`event-type-malformed`](/docs/eventsourcingdb/errors/event-type-malformed)**: The event type is not a reverse domain name, such as `BookAcquired`.
- **[`event-type-unknown`](/docs/eventsourcingdb/errors/event-type-unknown)**: The event type has neither events nor a schema, for example because of a typo.
- **[`indexes-rebuilding`](/docs/eventsourcingdb/errors/indexes-rebuilding)**: The indexes that the read needs are still being rebuilt after an upgrade.
- **[`restore-in-progress`](/docs/eventsourcingdb/errors/restore-in-progress)**: A restore is running, which refuses reads until it has finished.
- **[`file-unreadable`](/docs/eventsourcingdb/errors/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`](/docs/eventsourcingdb/errors/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](/docs/eventsourcingdb/api#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](/docs/eventsourcingdb/limits)**.
- **`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`.