One toolchain for every API you own
Andriy Mykulyak · · 6 min read
Take a team that is not unusual at all: a REST API for the web app, a few Kafka topics between services, one gRPC service that somebody wrote in Go, and a GraphQL gateway in front of it all. Everybody on that team agrees the contract should come first. Almost nobody works that way, because the “first” part means installing and maintaining a tool per job per format, and most teams quietly stop after the linter. I wrote about the symptom in We need better REST and about the cause in why schema-first never became mainstream.
API Genie is what I built to remove the cause: one set of tools that reads the five families and does each job on each of them. This series shows it on one example API, one job per post, every command run and its output pasted.
The zoo
If that team wants to lint, diff, mock and generate code for all of it, here is roughly what it installs today:
| Need | REST (OpenAPI) | Events (AsyncAPI) | gRPC (Protobuf) | GraphQL |
|---|---|---|---|---|
| Lint | Spectral (Node) | Spectral, AsyncAPI CLI (Node) | Buf (Go) | an ESLint plugin (Node) |
| Breaking changes | oasdiff (Go) | not much | buf breaking |
GraphQL Inspector (Node) |
| Changelog | a SaaS, or hand-written | hand-written | hand-written | a registry (SaaS) |
| Mock | Prism (Node) | Microcks (Java, needs a cluster) | hand-written stubs | a mocking library |
| Codegen | openapi-generator (Java) | AsyncAPI generator (Node) | protoc plus a plugin per language | a plugin per language |
| Docs | Redoc or Scalar | AsyncAPI Studio | protoc-gen-doc | a GraphiQL page |
Five runtimes, a dozen tools, each with its own configuration format, its own idea of what a severity is, its own exit codes and its own output. None of them knows about the others. The breaking-change checker for OpenAPI has no opinion about the Kafka event that carries the same schema. The mock for REST cannot publish the event the real backend would publish.
One toolchain
API Genie reads OpenAPI 3.0, 3.1 and 3.2, Swagger 2.0, AsyncAPI 3, GraphQL SDL and Protobuf 3, and converts WSDL 1.1 to OpenAPI. It installs as four native binaries, always of the same version:
| Binary | What it does |
|---|---|
apigenie |
Lints, formats, compares, bundles, converts and tests API documents |
apigenie-generator |
Generates clients, servers, documentation, data and validation schemas |
apigenie-server |
Serves a document as a mock server, or proxies a live API and checks the traffic against the contract |
apigenie-catalog |
Lists the API specifications of a repository (experimental) |
$ apigenie --version
0.10.0
apigenie-generator 0.10.0
apigenie-server 0.10.0
apigenie-catalog 0.10.0
“Native” matters more than it sounds. There is no Node, Java or Python runtime to install: the
binaries are C++, a few megabytes each, and the same code runs as WebAssembly in the browser,
which is how the editor and the docs renderer work. The whole thing is one
brew install, one npm install -g, one Docker image or one GitHub Action step.
One configuration file
Each command reads the same apigenie.yaml, found in the current directory or a parent up to
the root of the repository. The file has a published JSON Schema, so an editor that speaks the
YAML language server completes and checks it as you type:
# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json
version: "1.0"
commands:
lint:
extends: [recommended]
diff:
extends: [recommended]
format:
openapi: { indent: 2 }
generate:
server_spring:
overlay: [carpet-express.spring.overlay.yaml]
apigenie config prints what is in effect and where each value came from, and
apigenie config check tells you about a typo with its position and a suggestion. With format
misspelled in the file above:
$ apigenie config check apigenie.yaml
apigenie.yaml:6:5: /commands/fromat: unknown property 'fromat'; did you mean 'format'?
$ echo $?
2
One set of conventions
The four binaries share one table of exit statuses: 0 success, 1 findings (lint errors, breaking
changes, format --check differences), 2 a usage, input or unexpected error, 3 and 4 the server’s
document and address errors, 5 a failed contract or replay report. A CI job treats lint, diff,
format --check and test the same way. Each JSON report carries a formatVersion, and its
schema is published under apigenie.pl/schemas, so a dashboard that reads the lint report today
still reads it after the next minor release. The text formatters are the ones you know from
ESLint: stylish, compact, unix, visualstudio, checkstyle, html, json, junit, tap
and sarif.
The 1.0 promise
From 1.0.0, command names, option names, configuration keys, environment variables, exit
statuses, the JSON reports and the admin API of the server follow semantic versioning: a minor
release adds, only a major release removes. What is still moving says so in the first line of its
--help, “experimental, outside the 1.0 compatibility promise”: the catalog, convert,
evolve plan, the Zod schemas and the MCP server generator. The
Compatibility page is the contract.
The example that runs through the series
Each post in this series uses the same API: Carpet Express, a fictional multi-carrier shipping
platform in the spirit of Shippo or EasyPost. It has 27 paths and 38 operations (rate quotes,
polymorphic shipments, labels in four formats, customs paperwork, tracking, pickups, warehouses,
webhooks and async bulk imports), 72 schemas that use most of JSON Schema 2020-12, and an
AsyncAPI 3 companion with the same platform’s events over Kafka, WebSocket, MQTT, HTTP and AMQP.
It is deliberately not a petstore: it has the oneOf with a discriminator, the deepObject query
parameters, the multipart uploads and the deprecated legacy endpoint that real APIs have.
The files are on this site, with the inputs of each post:
curl -sSL https://apigenie.pl/examples/carpet-express.tar.gz | tar xz
cd carpet-express
apigenie lint carpet-express.openapi.yaml carpet-express.asyncapi.yaml
You will see the same API linted, evolved, contract-tested, generated and edited. If “one toolchain” is a real thing and not a slogan, that is where it shows.
What the series covers
Two posts of this blog already cover two of the jobs on their own examples:
Catching breaking changes with apigenie diff
and the mock server. The series picks up after them:
- One toolchain for every API you own (this post).
- Ship a breaking change without breaking anyone.
evolve planwrites the expand and contract waves for you and proves them withdiff. - The traffic you already have is the contract test.
The validating proxy,
apigenie test, session recording and replay. - Lint every API format with the rules you already have. Your Spectral rulesets, JavaScript functions included, without Node; fixes and SARIF.
- From spec to code in six languages, and to an MCP server. Clients, servers and Kafka applications from one document, tuned with overlays.
- Edit your spec in forms without losing a single byte. The editor, in VS Code, on the desktop and on the web.
A post goes out every Tuesday.
Try it
brew install mykulyak/apigenie/apigenie # macOS and Linux
npm install -g @mykulyak/api-genie # anywhere Node is
docker run --rm mykulyak/apigenie --version
Then apigenie --version, and the four lines above are yours. Next week:
Ship a breaking change without breaking anyone.