# openapi

Describes the **v2 API** as an **OpenAPI definition**.

- **Route:** `QUERY /api/v2/system/openapi`, and `GET` as well
- **Category:** `system`
- **Authentication:** none, the route is public
- **Answer:** an **[OpenAPI 3.2](https://spec.openapis.org/oas/v3.2.0.html)** document in JSON, not wrapped in an envelope

The definition describes **every route of the v2 API** that the server serves, this one included: its method, its request body, its answers with their schemas, including the **[error codes](/docs/eventsourcingdb/errors)** the route can report, and the status codes it documents. Use it to **generate client code**, to **explore the API**, or to load it into tools such as **[Postman](https://www.postman.com/)** or **[Swagger UI](https://swagger.io/tools/swagger-ui/)**, see **[OpenAPI Specification](/docs/eventsourcingdb/api#openapi-specification)**. The definition of the deprecated **v1 API** remains available as YAML at `/.well-known/openapi`.

## Request

The route takes **no body**, and ignores one that is sent. Besides `QUERY`, it answers `GET`, which API tools and code generators send:

```shell
curl \
  http://localhost:3000/api/v2/system/openapi
```

## Answer

The answer is the **OpenAPI document**, with the content type `application/json`. Its paths are **relative to the server URL `/api/v2`**, which the document names in `servers`, and its `info` names the version of the server. Its routes are grouped by their category, as tags. The routes of the **`ui`** category, which serve the **[management UI](/docs/eventsourcingdb/management-ui)** only, appear only while the management UI is enabled.

Shortened to the description of this very route for `GET`, and without its `info`, `components`, and `tags`, the request above is answered with:

```json
{
  "openapi": "3.2.0",
  "servers": [
    {
      "url": "/api/v2"
    }
  ],
  "paths": {
    "/system/openapi": {
      "get": {
        "summary": "Describes the v2 API as an OpenAPI document.",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "The OpenAPI document of the v2 API.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "required": [],
                  "description": "An OpenAPI 3.2 document.",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "The request exceeded the rate limit.",
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "The request caused an internal server error."
          },
          "503": {
            "description": "The server is shutting down."
          }
        }
      }
    }
  }
}
```

## 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)**:

- **`429`**: Too many requests were sent; the answer says when to try again.
- **`500`**: The server failed unexpectedly.
- **`503`**: The server is shutting down.