One mock server for every contract: meet apigenie-server
Andriy Mykulyak · · 7 min read
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.
.protofiles: 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:
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.
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 fallbacksends 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 DIRwrites the exchanges the server answered as stub files, and--stubs DIRreplays them later without the server.
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:
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:
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:
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 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
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 has every option, the full list of contract checks for each kind of document, the configuration file, the admin API, and the limits I know about, such as one document per server and no GraphQL federation. If you try the validating proxy against your own server and it reports something you think is wrong, I’d like to hear about it.