All articles
ProductIntroducing API Genie, part 1

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:

  1. One toolchain for every API you own (this post).
  2. Ship a breaking change without breaking anyone. evolve plan writes the expand and contract waves for you and proves them with diff.
  3. The traffic you already have is the contract test. The validating proxy, apigenie test, session recording and replay.
  4. Lint every API format with the rules you already have. Your Spectral rulesets, JavaScript functions included, without Node; fixes and SARIF.
  5. From spec to code in six languages, and to an MCP server. Clients, servers and Kafka applications from one document, tuned with overlays.
  6. 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.

Andriy Mykulyak builds API Genie.LinkedInXcontact@apigenie.pl
Was this helpful?

Try API Genie on your own schema

Run it with Docker or download a binary for your platform.

Get API Genie