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 Prefer header, 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-mock in 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 .proto file: 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: --record and --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.yaml and the commands.mock section of apigenie.yaml, with every key.
  • Dashboard and admin API: The page at /__apigenie/ui and 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 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). 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, 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.
Was this helpful?