# One mock server for every contract: meet apigenie-server

Source: https://apigenie.pl/blog/mocking-any-api-with-apigenie-server

## Why I care about mocks

In API-first work the contract comes before the code. That is the whole point: once the OpenAPI document, the AsyncAPI document, the `.proto` file or the GraphQL schema is agreed on, the frontend team, the backend team and the teams of other services can all start at once. In practice, though, the people consuming the API need something that answers HTTP requests, and the people building it need something that tells them whether they actually built what was agreed.

A mock server covers the first need. A validating proxy covers the second. I wanted one tool that does both, for every kind of contract API Genie works with, and that is what `apigenie-server` is. It is installed next to `apigenie` by every package (archives, `.deb`, `.rpm`, npm, Homebrew) and has a Docker image of its own. It used to be called `apigenie-mock`, and that name keeps working until 1.1.

## What it serves

You give it one document and it serves it:

- **OpenAPI 3.0, 3.1 and 3.2** documents as a mock HTTP API. **Swagger 2.0** documents are converted in memory to OpenAPI 3.2 (no file is written) and served the same way.
- **AsyncAPI 3.x** documents: the mock plays the application the document describes, over WebSocket, HTTP and MQTT. It runs its own MQTT broker, on port 1883 by default. Kafka, AMQP and other protocols are listed as not served.
- **`.proto` files**: their gRPC services over HTTP/2, on the same port as HTTP, with unary, server-streaming, client-streaming and bidirectional methods. Server reflection and the health service are built in, so grpcurl, buf curl and Postman can list the services.
- **GraphQL schemas**: a GraphQL endpoint at `/graphql`, with GraphiQL in the browser, introspection, and subscriptions over WebSocket and server-sent events. No resolvers to write.

Starting it is one command:

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

The first line it prints says where it listens, and `--log-format json` turns that line and every request after it into JSON, which is handy when a test harness has to parse the output.

## Where the responses come from

By default (`--static`) the mock answers with what the document already has: the media type's `example`, its first named example, or the schema's example. What has no example is generated from the schema, respecting types, formats such as `uuid`, `date-time` and `email`, patterns, lengths, ranges, `enum`, `allOf`, `oneOf`, `readOnly` and `writeOnly`. With `--dynamic` every response is generated. `--seed` makes generated data and simulated failures repeat from run to run, which matters more than it sounds once a test depends on a value.

A schema can name the faker function for its values with `x-faker` (`person.fullName`, `internet.email`), and GraphQL schemas take graphql-faker's `@fake` directive along with the mock's own `@mock`, `@examples` and `@listLength`. For GraphQL, objects with an `id` are kept in a small store, so asking for the same user twice gives the same name, and the usual `createUser`, `updateUser` and `deleteUser` mutations work on it.

Stubs are the third source. For gRPC you write them as YAML or JSON, matching requests by equality, subsets or regular expressions, with templates such as `{{request.name}}`. For OpenAPI the stubs are usually recorded rather than written, which I come back to below.

Every response carries `X-Apigenie-Mock-Source` (`example:cat`, `generated`, `stub:getPet-1`, ...), so you never have to guess why you got the answer you got. A client can also ask for a particular answer with the `Prefer` header: `code=404`, `example=cat`, `dynamic=true`, `delay=1500`, or `scenario=outage`.

## Validation in both directions

A mock that accepts anything teaches the frontend nothing. `apigenie-server` checks requests against their operation: path, query, header and cookie parameters, and JSON, form and multipart bodies. A request that doesn't match gets 422 with the problems, a body that isn't JSON gets 400, an unknown media type 415. Security requirements are checked for presence (401), and against configured credentials in `enforce` mode (403).

The mock checks its own responses too. Problems are logged and counted in `X-Apigenie-Mock-Violations`, or, with `--strict`, answered with 500. It catches examples that drifted away from their schemas.

## The validating proxy

This is the part I use most. With `--proxy-to`, an OpenAPI document is not mocked at all: every request goes to the real server, and the mock checks both the request and the server's response against the document.

```sh
apigenie-server openapi.yaml --proxy-to http://localhost:8080 --report contract.json --fail-on errors
```

Point your tests, your frontend or a load test at port 4010 instead of 8080, and that traffic becomes a contract test. Each problem is a violation with a check name, a severity and a location: `response.body.incompatible` for a body that doesn't match its schema, `response.status.unknown` for a status the document doesn't declare, `request.query.unknown` for an undeclared query parameter, and so on. `contract.severity` in the configuration changes a check's severity or turns it off.

By default the proxy only reports, because test suites send invalid requests on purpose to see the server refuse them. With `--strict` it enforces: an invalid request never reaches the server, and an invalid response is replaced with a 502 problem that explains what was wrong.

The same idea works for the other contract types. A GraphQL proxy checks every answer against the schema and the request's selection set, and also introspects the server and compares its schema with yours, reporting drift. An AsyncAPI proxy relays WebSocket and HTTP channels to a real server and MQTT channels to a real broker, checking messages in both directions. A gRPC proxy checks the messages of every call it forwards against the `.proto` file, including fields marked `REQUIRED` with `google.api.field_behavior`.

Two more modes make the proxy useful during development, not only in CI:

- `--proxy-mode fallback` sends every request to the server first, but lets the mock answer when the server can't be reached, doesn't answer in time, or answers 404 or 501 for an operation of the document. A frontend can work against a backend that is only half built.
- `--record-dir DIR` writes the exchanges the server answered as stub files, and `--stubs DIR` replays them later without the server.

```sh
apigenie-server openapi.yaml --proxy-to http://localhost:8080 --record-dir recorded
apigenie-server openapi.yaml --stubs recorded
```

Recorded values of `Authorization`, `Cookie` and similar headers are written as `[redacted]`. For OpenAPI, `--record-har` also writes the whole session as a HAR 1.2 file that browser developer tools and Postman can open.

## A slow, unreliable network on demand

Clients rarely fail on the happy path. They fail on a timeout, a reset connection, or a response that arrives after the user has already clicked again. The mock can make the network bad on purpose:

```sh
apigenie-server openapi.yaml --latency 100-300 --jitter 50 --drop-rate 0.05
```

`--latency` takes milliseconds or a `MIN-MAX` range, `--jitter` adds a random extra delay, and `--drop-rate` resets the connection for that share of responses. The configuration goes further: latency distributions, bandwidth limits, and dropped connections that close without an answer, never answer, or truncate the body. All of this can apply to every response, to one operation, to a scenario, or to a single request (`Prefer: drop=timeout`). Scenarios are named sets of rules, for example "every operation tagged `pets` answers 503", that you switch on with `--scenario` or through the admin API under `/__apigenie` while the mock runs.

## TLS

The mock serves TLS itself:

```sh
apigenie-server openapi.yaml --tls-cert localhost+1.pem --tls-key localhost+1-key.pem
```

The port becomes HTTPS, WebSocket channels and GraphQL subscriptions become WSS, and clients that ask for `h2` get HTTP/2, which is how browsers and gRPC clients over TLS connect. The proxies reach `https://`, `wss://` and `mqtts://` upstreams and verify their certificates against the system's roots; `--ca-cert` adds a company or test CA, and `--insecure` skips verification. TLS 1.2 and 1.3 come from Mbed TLS. Mutual TLS isn't supported, and the mock's own MQTT broker stays cleartext.

## In CI, with `apigenie test`

The validating proxy keeps a contract report as traffic goes through: which operations were covered, partially covered or not tested, and every violation. When the server stops, it writes `--report` (JSON) and `--report-junit` (JUnit XML), and exits with status 5 when `--fail-on` or `--min-coverage` isn't met. That makes an existing test suite into a contract gate with a few lines of shell:

```sh
apigenie-server openapi.yaml --proxy-to http://localhost:8080 --port 4010 \
  --report contract.json --report-junit contract.xml --fail-on errors --min-coverage 80 &
API_URL=http://localhost:4010 npm test
curl -X POST http://localhost:4010/__apigenie/shutdown
wait $!   # 5 when the contract failed
```

If you don't have a test suite to route through the proxy, [`apigenie test`](/docs/reference/cli/test) sends the requests itself, from `.http` files or generated from the document with `--generate`, and applies the same checks and the same report format. It has the same `--fail-on` and `--min-coverage` options, except that `--fail-on` defaults to `errors` there, so `apigenie test` fails on violations out of the box. The two fit together in the other direction as well: while the real server doesn't exist yet, the same `.http` files can run against the mock.

## Docker

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

The image listens on every interface of the container and exposes port 4010, plus 1883 for the MQTT broker. It includes CA certificates, so `https://` upstreams are verified, and you can mount a certificate and key to serve HTTPS.

## Where to go next

The [`apigenie-server` reference](/docs/reference/server) has every option, the full list of contract checks for each kind of document, the configuration file, the admin API, and the [limits](/docs/reference/server#limits) I know about, such as one document per server and no GraphQL federation. If you try the [validating proxy](/docs/reference/server/contract-testing) against your own server and it reports something you think is wrong, I'd like to hear about it.
