# One toolchain for every API you own

Source: https://apigenie.pl/blog/one-toolchain-for-every-api-you-own

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](/blog/we-need-better-rest-en)
and about the cause in [why schema-first never became mainstream](/blog/from-schema-first-to-apigenie).

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) |

```text
$ 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](/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
# 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:

```text
$ 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](/docs/reference/cli/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:

```sh
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`](/blog/catching-breaking-changes-with-apigenie-diff)
and [the mock server](/blog/mocking-any-api-with-apigenie-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

```sh
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.
