Server

Mock first, validate the real server later

apigenie-server serves responses from your contract while the backend is built, then checks the real server's traffic against the same contract.

Start a mock server Read the reference

Client work starts before the backendThe mock serves the contract's examples, stubs or generated data and validates every request. Front-end and client teams develop against it.
Your existing tests become contract testsPointed at the validating proxy, they check every request and response against the contract, with coverage and JSON or JUnit reports for CI.
Integration tests without the live servicesRecord a session once and replay its exchanges in order. The tests run against the recording instead of the real services.

The mock before the backend, the proxy in front of it

Before the backend exists, the server answers from the contract. Once it does, the same server sits in front of it and checks both directions.

The same binary and the same file in both positions. The dashboard shows the traffic either way.

Start a mock from your contract

Point the server at an API description. It serves the mock and a dashboard for inspecting requests, responses and contract violations.

$ apigenie-server openapi.yaml
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

A successful response, a broken contract

Restart with --proxy-to to validate the real server's traffic. Here the server returns HTTP 200, but id is a string where the contract requires an integer. The response headers identify the field and the mismatch. On shutdown, --report writes the report and --fail-on errors returns status 5 if an error-level violation was found.

$ apigenie-server openapi.yaml --proxy-to http://localhost:8080 \
    --report contract.json --fail-on errors
$ # In another terminal, with the upstream returning {"id":"42"}:
$ curl -si http://127.0.0.1:4010/v1/pets/42 | grep -E '^HTTP|^X-Apigenie-Mock-Violations'
HTTP/1.1 200 OK
X-Apigenie-Mock-Violations: 1
X-Apigenie-Mock-Violations-Detail: [{"location":["response","body","/id"],"check":"response.body.incompatible","code":"type","severity":"error","message":"expected type integer, found string"}]

Four kinds of API

OpenAPI and Swagger 2.0HTTP APIs, with CRUD resources kept in a document store when you ask for them.
AsyncAPIWebSocket, HTTP and MQTT channels, with a built-in MQTT broker.
Protobuf and gRPCThe services of a .proto file, answered by stubs or forwarded to a real server.
GraphQLA GraphQL endpoint with GraphiQL and subscriptions over WebSocket.

What comes with it

The apigenie-server dashboard: a table of mock requests with their status, source and contract violations

DashboardTraffic as it happens, the operations and what answers them, scenarios, the contract report and the data, in the browser.
ScenariosSwitch on errors, slow answers or other examples for some operations, from the configuration, the document or the dashboard.
Network simulationLatency, jitter and dropped connections, repeatable with a seed.
ScriptsJavaScript hooks that change requests and responses or keep state between them.
Several servicesMany documents on one port, each under its own prefix.
TLS and mTLSHTTPS, WSS, gRPC and MQTT over TLS, client certificates, and verified upstreams.

Install

The CLI packages include apigenie-server, also available as the mykulyak/apigenie-server Docker image. To send test requests without a proxy, use apigenie test.

Use cases

Start a mock server Read the reference