apigenie-server
apigenie-server serves an OpenAPI 3.0, 3.1 or 3.2 document (or a Swagger 2.0 one, see
Swagger 2.0 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: Routing, the status, body and headers of an answer, the
Preferheader, and latency, drops and bandwidth limits. - Validation and security: What is checked in requests and responses, the security schemes, and XML bodies.
- Contract testing (validating proxy):
--proxy-to: the checks on a real server’s traffic, coverage, and the JSON and JUnit reports. - Scenarios and extensions: Named sets of rules, from the configuration,
x-apigenie-mockin the document or the admin API. - AsyncAPI: The channels of an AsyncAPI document over WebSocket, HTTP and MQTT, and the contract testing of each protocol.
- Protobuf / gRPC: The gRPC services of a
.protofile: stubs, metadata, proxy and record, and contract testing. - GraphQL: A GraphQL endpoint from a schema: generated data, the store, examples, scenarios, subscriptions and the proxy.
- Scripts: JavaScript that computes answers and reads the log and the store.
- Session recording and replay:
--recordand--replay: a run as files, replayed as a mock or in a test suite. - Several services: One server for several documents.
- Document store: The data behind the answers, and CRUD resources.
- Configuration:
apigenie-server.yamland thecommands.mocksection ofapigenie.yaml, with every key. - Dashboard and admin API: The page at
/__apigenie/uiand the endpoints behind it. - TLS: HTTPS with
--tls-cert, and client certificates.
Usage
apigenie-server [OPTIONS] SPEC...
apigenie-server session export DIR --har FILE
apigenie-server openapi.yaml
curl http://127.0.0.1:4010/pets
The first line the server writes says where it listens:
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 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:
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 } } }"}'
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):
apigenie-server openapi.yaml --proxy-to http://localhost:8080
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):
apigenie-server pets.yaml orders.yaml events.asyncapi.yaml
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 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: what a POST creates, a GET lists. The same as db.crud: auto. |
|
--db-file FILE |
Keep the document 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). OpenAPI: the exchanges --record-dir wrote (see Record and replay). 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). GraphQL: the real server’s endpoint (https://host/graphql), requests and answers checked against the schema (see GraphQL contract testing). 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, MQTT contract testing and 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). https://, wss:// and mqtts:// upstreams are verified (see 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. 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. 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); 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). 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). 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: 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:
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
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
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 theAPIGENIE_SERVER_*variable of the same name is unset.mykulyak/apigenie-mock: itslatesttag 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). 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
.protodocument’s hash covers the file, not its imports; MQTT messages keep neither QoS nor retain nor MQTT 5 properties;session exportleaves 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, 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, andreadOnlyproperties 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:typearen’t mapped, andnodeType: noneis 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),@deferand@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 (@specifiedByURLs,@oneOf, repeatable directives, deprecated arguments) and the directives applied in the schema.