# HTTP API

Virtual Printer speaks two protocols, and it matters which one does what.

- **HTTP/REST** — create workspaces and printers, read parsed documents back, inject hardware faults,
  subscribe to event streams. Everything under `/api`.
- **Raw TCP** — the printing itself. A client opens a socket to `settings.publicHost` on
  `settings.tcpListenPort` and writes ESC/POS or EPL bytes. This step is deliberately *not* HTTP and is
  therefore not in the OpenAPI spec.

A test or integration normally uses both: HTTP to set the printer up and to assert on the result, raw
TCP in between for the part that must behave like real hardware.

## Reference

- [Endpoint reference](/docs/api/endpoints) — every endpoint with its request and response shapes, the
  `problem+json` error map, the SSE streams, and the full end-to-end scenario.
- [Printer status API](/docs/api/printer-status) — start/stop, operational flags, cash drawer, and
  status streaming in detail.
- [CI/CD and automated tests](/docs/ci-cd) — the same endpoints arranged as a test workflow.

## OpenAPI

A live spec is generated from the controllers and served by the application itself:

- Swagger UI: [`/swagger`](/swagger)
- Raw spec: [`/swagger/v1/swagger.json`](/swagger/v1/swagger.json)

It covers the HTTP surface only, for the reason above.

## Conventions worth knowing up front

- JSON is **PascalCase** (`Token`, `AccessToken`, `Id`).
- Null properties are omitted from responses, with one deliberate exception:
  `Printer.LastDocumentReceivedAt` is always present and may be `null`.
- IDs for workspaces and printers are **supplied by the caller** as GUIDs, which makes creates easy to
  assert against and re-run.
- Every authorized endpoint takes `Authorization: Bearer <AccessToken>` from
  [`POST /api/auth/login`](/docs/api/endpoints).