# apigenie-server

Source: https://apigenie.pl/docs/reference/server
See also: [Responses](https://apigenie.pl/docs/reference/server/responses.md), [Scenarios and extensions](https://apigenie.pl/docs/reference/server/scenarios.md), [Scripts](https://apigenie.pl/docs/reference/server/scripts.md), [Document store](https://apigenie.pl/docs/reference/server/store.md), [Several services](https://apigenie.pl/docs/reference/server/services.md), [Validation and security](https://apigenie.pl/docs/reference/server/validation.md), [Contract testing (validating proxy)](https://apigenie.pl/docs/reference/server/contract-testing.md), [Session recording and replay](https://apigenie.pl/docs/reference/server/recording.md), [AsyncAPI](https://apigenie.pl/docs/reference/server/asyncapi.md), [Protobuf / gRPC](https://apigenie.pl/docs/reference/server/grpc.md), [GraphQL](https://apigenie.pl/docs/reference/server/graphql.md), [Configuration](https://apigenie.pl/docs/reference/server/configuration.md), [Dashboard and admin API](https://apigenie.pl/docs/reference/server/dashboard.md), [TLS](https://apigenie.pl/docs/reference/server/tls.md).

`apigenie-server` serves an OpenAPI 3.0, 3.1 or 3.2 document (or a Swagger 2.0 one, see
[Swagger 2.0 documents](#swagger-20-documents)) as a mock API, the channels of an
AsyncAPI 3.x document over WebSocket, HTTP and MQTT, the gRPC services of a `.proto` file, or
a GraphQL schema as a GraphQL endpoint with subscriptions. It answers with the document's
examples, with stubs, or with data generated from its schemas, validates requests, responses
and messages, logs every exchange, and can make the network slow or unreliable on purpose. In
front of a real server (`--proxy-to`) it becomes a validating proxy that contract-tests the
server's traffic against the OpenAPI or Swagger document, the GraphQL schema, the AsyncAPI
document (WebSocket, MQTT and HTTP channels) or the `.proto` file, with coverage and JSON or JUnit
reports. It is
installed next to `apigenie` by every package (archives, `.deb`, `.rpm`, npm, Homebrew) and has a
Docker image of its own.

## Topics

- [Responses](/docs/reference/server/responses): Routing, the status, body and headers of an answer, the `Prefer` header, and latency, drops and bandwidth limits.
- [Validation and security](/docs/reference/server/validation): What is checked in requests and responses, the security schemes, and XML bodies.
- [Contract testing (validating proxy)](/docs/reference/server/contract-testing): `--proxy-to`: the checks on a real server's traffic, coverage, and the JSON and JUnit reports.
- [Scenarios and extensions](/docs/reference/server/scenarios): Named sets of rules, from the configuration, `x-apigenie-mock` in the document or the admin API.
- [AsyncAPI](/docs/reference/server/asyncapi): The channels of an AsyncAPI document over WebSocket, HTTP and MQTT, and the contract testing of each protocol.
- [Protobuf / gRPC](/docs/reference/server/grpc): The gRPC services of a `.proto` file: stubs, metadata, proxy and record, and contract testing.
- [GraphQL](/docs/reference/server/graphql): A GraphQL endpoint from a schema: generated data, the store, examples, scenarios, subscriptions and the proxy.
- [Scripts](/docs/reference/server/scripts): JavaScript that computes answers and reads the log and the store.
- [Session recording and replay](/docs/reference/server/recording): `--record` and `--replay`: a run as files, replayed as a mock or in a test suite.
- [Several services](/docs/reference/server/services): One server for several documents.
- [Document store](/docs/reference/server/store): The data behind the answers, and CRUD resources.
- [Configuration](/docs/reference/server/configuration): `apigenie-server.yaml` and the `commands.mock` section of `apigenie.yaml`, with every key.
- [Dashboard and admin API](/docs/reference/server/dashboard): The page at `/__apigenie/ui` and the endpoints behind it.
- [TLS](/docs/reference/server/tls): HTTPS with `--tls-cert`, and client certificates.

## Usage

```sh
apigenie-server [OPTIONS] SPEC...
apigenie-server session export DIR --har FILE
```

```sh
apigenie-server openapi.yaml
curl http://127.0.0.1:4010/pets
```

The first line the server writes says where it listens:

```text
Listening on http://127.0.0.1:4010/v1 (spec: openapi.yaml, 12 operations)
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui
```

The [dashboard](/docs/reference/server/dashboard#dashboard) shows the traffic as it happens, the operations and what answers
them, the scenarios, the contract report, the data and, for an AsyncAPI document, the channels
and their clients, in the browser.

A GraphQL schema (`.graphql`, `.graphqls`, `.gql`) is served at `/graphql`:

```sh
apigenie-server schema.graphql
curl -X POST http://127.0.0.1:4010/graphql -H 'Content-Type: application/json' \
  -d '{"query": "{ books { title author { name } } }"}'
```

```text
Listening on http://127.0.0.1:4010/graphql (spec: schema.graphql, 12 operations)
GraphiQL: http://127.0.0.1:4010/graphql
Subscriptions: ws://127.0.0.1:4010/graphql
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui
```

In front of a real server it checks the traffic against the document instead of mocking it
([contract testing](/docs/reference/server/contract-testing)):

```sh
apigenie-server openapi.yaml --proxy-to http://localhost:8080
```

```text
Listening on http://127.0.0.1:4010/v1 (spec: openapi.yaml, 12 operations)
Proxy: http://localhost:8080 (requests: log, responses: log, unknown routes: forward, mode: always)
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui
```

With `--log-format json` it is a JSON object (`{"event":"listening","url":...,"port":...}`), and
every request after it is logged as one JSON object per line, which suits tools and tests.

Several documents are served together on one port, each below a prefix of its own
([several services](/docs/reference/server/services)):

```sh
apigenie-server pets.yaml orders.yaml events.asyncapi.yaml
```

```text
Listening on http://127.0.0.1:4010 (3 services)
  pets    http://127.0.0.1:4010/pets/v1 (spec: pets.yaml, 12 operations)
  orders  http://127.0.0.1:4010/orders (spec: orders.yaml, 5 operations)
  events  http://127.0.0.1:4010/events (spec: events.asyncapi.yaml, 3 channels)
Admin API: http://127.0.0.1:4010/__apigenie
Dashboard: http://127.0.0.1:4010/__apigenie/ui
```

## Options

| Option | Default | Description |
| --- | --- | --- |
| `--host HOST` | `127.0.0.1` | The address to listen on; `0.0.0.0` or `::` for every interface. Also `APIGENIE_SERVER_HOST`. |
| `--port`, `-p PORT` | `4010` | The port; `0` picks a free one. Also `APIGENIE_SERVER_PORT`. |
| `--base-path PATH` | the servers' paths | Serve the operations under this prefix instead of the paths of the document's `servers`. |
| `--config`, `-c FILE` | see below | The configuration file. |
| `--no-config` | | Don't look for a configuration file. |
| `--watch`, `-w` | | Reload when the document or the configuration changes. A broken version is reported and the previous one stays. |
| `--seed N` | random | Seed of generated data and simulated failures: the same seed repeats a run. |
| `--dynamic`, `-d` / `--static` | `--static` | Generate every response from its schema, or answer with examples first. |
| `--strict` | | Answer 500 when a response the mock makes doesn't match the document. With `--proxy-to`: answer requests that don't match the document or schema without the upstream (422 for OpenAPI, GraphQL errors for GraphQL) and replace upstream responses that don't (502); AsyncAPI: messages that don't match aren't forwarded, the client gets a problem message instead; gRPC: requests and upstream messages are checked before they are forwarded, and a call that breaks the contract ends with INVALID_ARGUMENT or INTERNAL. |
| `--log-format FORMAT` | `stylish` | `stylish` or `json`. |
| `--log-level LEVEL` | `info` | `debug`, `info`, `warn` or `error`. |
| `--log-file FILE` | | Also write the log to a file, as JSON lines. |
| `--log-bodies`, `--log-headers` | | Log request and response bodies, request headers. |
| `--quiet`, `-q` | | Only the first line on the standard output. |
| `--latency MS` | | Delay every response: a number of milliseconds, or `MIN-MAX`. |
| `--jitter MS` | | A random extra delay of up to this many milliseconds. |
| `--drop-rate RATE` | | The share of responses (0 to 1) whose connection is reset. |
| `--cors on\|off` | `on` | Answer CORS preflights and add CORS headers. |
| `--admin on\|off` | `on` | The admin API under `/__apigenie`, and the [dashboard](/docs/reference/server/dashboard#dashboard) at `/__apigenie/ui`. |
| `--scenario NAME` | | Switch on a scenario of the configuration or the document; can be repeated. |
| `--script FILE` | | A JavaScript module with hooks (see below); can be repeated. |
| `--crud` | | Serve the collection resources of an OpenAPI document (`/things` and `/things/{id}`) from the [document store](/docs/reference/server/store#crud-resources): what a `POST` creates, a `GET` lists. The same as `db.crud: auto`. |
| `--db-file FILE` | | Keep the [document store](/docs/reference/server/store) in this JSON file: loaded at the start, written when the server stops. Also `APIGENIE_SERVER_DB_FILE`. |
| `--asyncapi-server NAME` | every server | AsyncAPI: serve this server of the document only. |
| `--mqtt-port PORT` | `1883`, `8883` with `--tls-cert` | AsyncAPI: the port of the MQTT broker; `0` picks a free one. Also `APIGENIE_SERVER_MQTT_PORT`. |
| `--proto-path`, `-I DIR` | the file's directory | gRPC: where imports are looked up, like protoc's `--proto_path`; can be repeated. Also `APIGENIE_SERVER_PROTO_PATH` (separated by `:`, `;` on Windows). |
| `--stubs FILE\|DIR` | | A YAML or JSON stub file, or a directory of them; can be repeated. gRPC: stubs (see [Stubs](/docs/reference/server/grpc#stubs)). OpenAPI: the exchanges `--record-dir` wrote (see [Record and replay](/docs/reference/server/contract-testing)). Also `APIGENIE_SERVER_STUBS`. |
| `--proxy-to TARGET` | | OpenAPI: the real server (`http[s]://host[:port][/prefix]` or `HOST:PORT`) that gets every request, both checked against the document (see [Contract testing](/docs/reference/server/contract-testing)). GraphQL: the real server's endpoint (`https://host/graphql`), requests and answers checked against the schema (see [GraphQL contract testing](/docs/reference/server/graphql#contract-testing-of-a-graphql-api)). AsyncAPI: the real WebSocket and HTTP server (`ws[s]://host[:port][/prefix]` or `http[s]://...`) and the real MQTT broker (`mqtt[s]://host[:port]`), one or both (repeat the option), the messages of both sides checked against the document (see [WebSocket contract testing](/docs/reference/server/asyncapi#contract-testing-of-a-websocket-api), [MQTT contract testing](/docs/reference/server/asyncapi#contract-testing-of-mqtt-channels) and [HTTP channels](/docs/reference/server/asyncapi#contract-testing-of-http-channels)). gRPC: an upstream server for the calls no stub answers, `HOST:PORT` for cleartext HTTP/2 or `https://host[:port]` for HTTP/2 over TLS, its answers checked against the `.proto` file (see [gRPC contract testing](/docs/reference/server/grpc#contract-testing-of-a-grpc-api)). `https://`, `wss://` and `mqtts://` upstreams are verified (see [TLS](/docs/reference/server/tls)). Also `APIGENIE_SERVER_PROXY_TO` (one target). |
| `--tls-cert FILE` | | Serve HTTPS, WSS, gRPC and MQTT over TLS with this PEM certificate chain (the server's certificate first); needs `--tls-key`. See [TLS](/docs/reference/server/tls). Also `APIGENIE_SERVER_TLS_CERT`. |
| `--tls-key FILE` | | The unencrypted PEM private key of `--tls-cert`. Also `APIGENIE_SERVER_TLS_KEY`. |
| `--tls-client-ca FILE` | | Require a client certificate issued by the authorities of this PEM file on every HTTPS, WSS, gRPC and MQTTS connection (mTLS); the subject goes into the log and the contract report. Needs `--tls-cert`. See [Client certificates](/docs/reference/server/tls#client-certificates-mtls). Also `APIGENIE_SERVER_TLS_CLIENT_CA`. |
| `--ca-cert FILE` | the system's roots | A PEM file of certificate authorities trusted for `https://`, `wss://` and `mqtts://` upstreams, besides the system's; can be repeated. Also `APIGENIE_SERVER_CA_CERT` (separated by `:`, `;` on Windows). |
| `--insecure` | | Don't verify the certificates of `https://`, `wss://` and `mqtts://` upstreams; the traffic stays encrypted. Also `APIGENIE_SERVER_INSECURE=1`. |
| `--client-cert FILE` | | A PEM client certificate (chain) presented to `https://`, `wss://`, `mqtts://` and gRPC TLS upstreams that ask for one (mTLS); needs `--client-key`. Also `APIGENIE_SERVER_CLIENT_CERT`. |
| `--client-key FILE` | | The unencrypted PEM private key of `--client-cert`. Also `APIGENIE_SERVER_CLIENT_KEY`. |
| `--proxy-mode always\|fallback` | OpenAPI and GraphQL `always`, gRPC `fallback` | `always`: the upstream gets every request. `fallback`: OpenAPI: every request still goes to the server, and the mock answers when the server can't be reached, doesn't answer in time, or answers 404 or 501 for an operation of the document (see [Fallback mode](/docs/reference/server/contract-testing)); GraphQL: the mock's examples, scenarios and scripts answer first; gRPC: stubs answer first. An AsyncAPI document's proxy relays every message. |
| `--record-dir DIR` | | OpenAPI: write the exchanges the server answered as stub files, replayed with `--stubs`. gRPC: write the proxied calls as stub files. GraphQL: write the proxied answers as examples. Needs `--proxy-to`. Also `APIGENIE_SERVER_RECORD_DIR`. |
| `--record-har FILE` | | OpenAPI: write every exchange through the proxy (the server's answers and the mock's own) as a HAR 1.2 file when the server stops. Needs `--proxy-to`. Also `APIGENIE_SERVER_RECORD_HAR`. |
| `--record DIR` | | Record the session: every service's exchanges and messages in the order they happened, each as a file, and `session.yaml`; an exchange's test is its `X-Apigenie-Test` header (see [Session recording](/docs/reference/server/recording#session-recording)). Every document, with or without `--proxy-to`. The directory must be new or empty. Also `APIGENIE_SERVER_RECORD`. |
| `--record-redact HEADER\|/POINTER` | | What `--record` hides besides `Authorization`, `Cookie`, `Set-Cookie`, `Proxy-Authorization` and `X-Api-Key`: a header name, or a JSON pointer (`/password`) to a value of JSON bodies and messages; can be repeated. |
| `--replay DIR` | | Answer from the session `--record` wrote: each request gets the next unused recorded exchange of its test (`X-Apigenie-Test`) that matches it, on every protocol (see [Session replay](/docs/reference/server/recording#session-replay)). When the server stops, exit status 5 if a recorded exchange was never replayed or a request matched none. Also `APIGENIE_SERVER_REPLAY`. |
| `--replay-ignore HEADER\|/POINTER` | | What `--replay` doesn't compare besides dates, `readOnly` fields and volatile headers: a header name, or a JSON pointer (`/id`, `/items/*/id`) into JSON bodies and messages; can be repeated. |
| `--replay-missing fail\|generate\|passthrough` | `fail` | What a request no recorded exchange matches gets: a 502 problem naming the closest recording and how the request differs (`fail`), the mock's own answer (`generate`), or the answer of `--proxy-to` (`passthrough`). |
| `--replay-update` | | With `--replay-missing passthrough`: record the run and, when the server stops, replace the `--replay` session with it. |
| `--proxy-unknown forward\|reject` | `forward` | OpenAPI proxy: forward requests for no operation of the document (reported), or answer them with 404 or 405. |
| `--report FILE` | | Write the contract report (coverage and violations) as JSON when the server stops. Also `APIGENIE_SERVER_REPORT`. |
| `--report-junit FILE` | | Write the contract report as JUnit XML when the server stops. Also `APIGENIE_SERVER_REPORT_JUNIT`. |
| `--fail-on none\|errors\|warnings` | `none` | Exit with 5 when the server stops after violations of that severity. |
| `--min-coverage PERCENT` | | Exit with 5 when the server stops with less of the document covered (a GraphQL schema: its fields; an AsyncAPI document: its operations' messages; a `.proto` file: its methods; [several services](/docs/reference/server/services): their combined coverage). |
| `--credits`, `--license [LIBRARY]`, `--license-list` | | Like `apigenie credits` and `apigenie license`. |
| `--help`, `-h` / `--version`, `-v` | | Show the help (with the exit statuses and the per-request directives), or the version. |

## Exit status

| Code | Meaning |
| --- | --- |
| 0 | Stopped with Ctrl+C (or `POST /__apigenie/shutdown`) |
| 2 | Bad options, configuration, scripts or stub files, or an unexpected error |
| 3 | The document can't be served (missing, unreadable, not OpenAPI 3, Swagger 2.0 or AsyncAPI 3, no channels the mock serves, a `.proto` file with errors, missing imports or no services) |
| 4 | The address can't be used (the port is taken, ...) |
| 5 | The contract report failed when the server stopped (`--fail-on`, `--min-coverage`), or the replay did (`--replay`: a recorded exchange was never replayed, or a request matched none) |
| 130 | Stopped at once with a second Ctrl+C |

## Swagger 2.0 documents

A Swagger 2.0 document (`swagger: "2.0"`) is served, proxied and contract-tested like the
OpenAPI 3.2 document `apigenie convert --to openapi32` would make of it. The
conversion happens in memory each time the document is read (at startup and on reloads); no file
is written. Body and form parameters become request bodies, `produces` and `consumes` become
media types, `host`, `basePath` and `schemes` become the servers, and `definitions`, `parameters`,
`responses` and `securityDefinitions` move into `components`.

Locations stay those of the Swagger file: warnings about the document give its lines, the problems
of `x-apigenie-mock` extensions its lines and JSON pointers, and the contract report's `pointer`
of each operation is a pointer into it. What the conversion can only approximate (a
`collectionFormat` without counterpart, form parameters next to a body parameter, ...) is told
once at startup, on the standard error, as an `info:` line with the file's line, column and JSON
pointer:

```text
info: pets.yaml:7:71: /paths/~1pets/get/parameters/0/collectionFormat: collectionFormat tsv has no counterpart and becomes style form (csv)
```

`GET /__apigenie/spec` returns the converted document, which is what is served. The document is
converted alone: one that references other files can't be served (exit status 3) until
`apigenie bundle` has put them into it.

## Docker

```sh
docker run --rm -p 4010:4010 -v "$PWD:/mnt/data" mykulyak/apigenie-server openapi.yaml
```

It serves GraphQL schemas the same way (`mykulyak/apigenie-server schema.graphql`).

The image listens on every interface of the container (`APIGENIE_SERVER_HOST=0.0.0.0`) and exposes
port 4010, and 1883 for the MQTT broker (`-p 1883:1883`). It has the CA certificates of Alpine
Linux, so `https://` upstreams are verified; mount a certificate and its key to serve HTTPS
(`-v "$PWD/certs:/certs" ... --tls-cert /certs/server.pem --tls-key /certs/server.key`).

## npm

```sh
npx --package @mykulyak/api-genie apigenie-server openapi.yaml
```

## Deprecated names

`apigenie-server` was called `apigenie-mock` before. The `apigenie-mock` command was removed in
1.0: run `apigenie-server` instead. These old names keep working until 1.1, with a one-line notice
on standard error:

- `APIGENIE_MOCK_*` variables: read when the `APIGENIE_SERVER_*` variable of the same name is
  unset.
- `mykulyak/apigenie-mock`: its `latest` tag only prints the new image name and exits with 2; the
  older tags still hold the old server.

What did not change: the `apigenie-mock.yaml` configuration file (still read, after
`apigenie-server.yaml`), the `commands.mock` section of a shared configuration, the
`x-apigenie-mock` extensions, the `X-Apigenie-Mock-*` headers and the `/__apigenie` admin API.

## Limits

- TLS: no session resumption, no revocation checks (OCSP, CRLs) of server or client certificates
  (see [Client certificates](/docs/reference/server/tls#client-certificates-mtls)). The OpenAPI and
  GraphQL proxies speak HTTP/1.1 to the server, a connection per request; the AsyncAPI one connects
  to WebSocket servers without extensions. The AsyncAPI proxy relays WebSocket messages up to
  16 MiB; of MQTT 5 it relays the message properties, not those of CONNECT, SUBSCRIBE or
  DISCONNECT, nor subscription options and identifiers, and the broker publishes wills without
  their delay. Request and response bodies are buffered (16 MiB by default), so streams such as
  server-sent events don't fit. A HAR file is kept in memory until the server stops. OpenAPI
  stubs match exact paths and queries, not templates.
- gRPC: native gRPC over HTTP/2 (cleartext, or TLS with `--tls-cert`) only; gRPC-Web, the Connect protocol and REST
  transcoding (`google.api.http`) aren't served, and messages can't be compressed. Reflection
  doesn't include custom options.
- Several services: one MQTT broker for all of them, so an `mqtt://` upstream goes with one
  document; one HAR file. Services can't be added or removed without a restart.
- Session recording: exchanges are numbered in the order they completed; a gRPC call keeps at
  most 100 messages per side, a session at most 10 000 exchanges; a `.proto` document's hash
  covers the file, not its imports; MQTT messages keep neither QoS nor retain nor MQTT 5
  properties; `session export` leaves WebSocket and MQTT messages out of the HAR file.
- The document store is the OpenAPI document's and the scripts'; the GraphQL mock keeps its own
  [store](/docs/reference/server/graphql#the-store), and AsyncAPI and gRPC mocks see the documents only through scripts. CRUD
  resources are a path and its items' path: nested collections (`/users/{id}/orders`) are
  collections of their own, not filtered by the parent's id, and `readOnly` properties are filled
  in at the top level only.
- AsyncAPI: Kafka, AMQP and other protocols aren't served; Avro and Protobuf payloads are sent
  from their examples only, and not validated. The MQTT broker keeps no sessions between
  connections and sends at most QoS 1.
- XML bodies: no DTDs (and so no entities but the five predefined ones), UTF-8 and UTF-16 only;
  mixed content and `xsi:type` aren't mapped, and `nodeType: none` is honoured on arrays only.
- Callbacks, webhooks and links are not mocked. OpenAPI 3.2 streams described by
  `itemSchema` (server-sent events, JSON Lines) are answered with an empty body.
- GraphQL: no federation (`_entities`, `_service`), `@defer` and `@stream`, persisted queries or
  file uploads. Scenarios don't apply to subscriptions over WebSocket or server-sent events. The
  proxy doesn't forward subscriptions, and its schema check leaves out what only recent servers
  introspect (`@specifiedBy` URLs, `@oneOf`, repeatable directives, deprecated arguments) and the
  directives applied in the schema.
