# Two October releases, from translations to a fourth binary

Source: https://apigenie.pl/blog/two-october-releases

If you installed API Genie before October, two releases sit between your binary and the current one: 0.9.0 on 10 October and 0.10.0 on 25 October. The [changelog](/changelog) lists more than three hundred entries for the two. This is the shorter read: what each release adds, what you change when you upgrade, and what the binaries print, taken from a run of 0.10.0.

Since 0.10.0, `apigenie --version` lists the binaries installed next to it, and there are four:

```text
$ apigenie --version
0.10.0
apigenie-generator 0.10.0
apigenie-server 0.10.0
apigenie-catalog 0.10.0
```

A script that compares the version reads the first line: `apigenie --version | head -n 1`.

## 0.9.0, 10 October

In the changelog's words: API Genie 0.9.0 translates OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files, and its mock server mocks and contract-checks HTTP, WebSocket, MQTT, gRPC and GraphQL APIs. The new GitHub Action `mykulyak/api-genie-action` installs the CLI in workflows on Linux, macOS and Windows.

- **Translations for all five standards.** `apigenie i18n extract` and `i18n apply` work on OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files. The texts are extracted keyed by JSON pointers, declaration names or schema coordinates, and the translations are put back without touching the rest of the file.
- **Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS.** `apigenie test` runs `.http` files and generated requests against a live API. The mock server with `--proxy-to` sits between clients and a real server or broker and checks every request and response against the contract. Both report coverage, write JSON and JUnit reports, and fail CI with `--fail-on` and `--min-coverage`. The mock serves HTTPS, WSS and gRPC over TLS, and requests and upstreams can be `https://`, `wss://` and `mqtts://`.
- **Code generation for five stacks.** Clients and servers for TypeScript, Python, Go, Java and C#, from OpenAPI 3.0 to 3.2 and, for event-driven APIs, AsyncAPI 3.x. Every target is checked by a conformance suite: snapshots, the target's own compiler and linter, and a run against the validating proxy. The generators are a separate executable, `apigenie-generator`, installed with the CLI.
- **Web components for every spec type, and `generate docs`.** The `apg-*` custom elements document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL APIs, with Try it out for HTTP and GraphQL, built on the same engine as the CLI compiled to WebAssembly. `apigenie-generator docs` compiles any of these files, several at once, into a docs bundle that the components render into a static site.

What you change when you come from 0.8:

- `apigenie generate` is `apigenie-generator`. Drop `generate` from the command line: `apigenie generate client fetch spec.yaml -o out` becomes `apigenie-generator client fetch spec.yaml -o out`. The options and the `commands.generate` section of the configuration are unchanged.
- `generate doc html` is replaced by `apigenie-generator docs`, with no alias. The output is a docs bundle and an npm project, no longer an Astro project; `npm install && npm run build` still builds the site.
- The binaries link Mbed TLS for `https://`, `wss://` and `mqtts://` connections. Verifying servers needs the system's CA certificates: the Docker images include them, a minimal image of your own needs `ca-certificates`.
- Telemetry is opt-in. The CLI writes no `.apigenie.telemetry` file and sends nothing; old files can be deleted.
- `apigenie i18n FILE --output DEST` becomes `apigenie i18n extract FILE --output DEST`.
- `lint` exits with status 1 when errors remain, so a CI job that ran it for its report fails now. Lower the severities in the configuration to keep it passing.

## 0.10.0, 25 October

In the changelog's words: the mock server is now `apigenie-server`, with a document store for CRUD resources and several services in one process, and a fourth binary, `apigenie-catalog`, keeps a repository's API catalog. `apigenie-generator` applies OpenAPI overlays before generating, and the three binaries share one table of exit statuses.

- **`apigenie-server`**, the mock server and validating proxy under its new name, with a dashboard at `/__apigenie/ui` (Traffic, Operations, Scenarios, Contract, Data and, for AsyncAPI, Channels), several services on one port with a prefix each, a document store (`db.crud: auto` resources, seeding, snapshots), session recording and replay (`--record DIR`, `--replay DIR`), client certificates, MQTT 5 properties, and validating proxies for Kafka and AMQP brokers.
- **`apigenie-catalog`**, a fourth binary, experimental: `catalog list` finds the API specifications of a repository and `catalog init` records them in `apigenie.yaml`. Run on a directory with the two Carpet Express documents of this blog's series:

  ```text
  $ apigenie-catalog list
  apigenie-catalog (experimental, outside the 1.0 compatibility promise)
  NAME                           FORMAT          VERSION  PATH                          COMMIT
  carpet-express-event-platform  AsyncAPI 3.0.0  2.4.0    carpet-express.asyncapi.yaml  -
  carpet-express-shipping-api    OpenAPI 3.2.0   2.4.0    carpet-express.openapi.yaml   -
  ```

- **Code generation:** `--overlay FILE` on every OpenAPI and AsyncAPI target; the Elixir family (`client elixir` and `server phoenix` for OpenAPI and AsyncAPI, `server absinthe` for GraphQL, `server elixir-grpc` and the Elixir gRPC client for Protobuf); `server mcp`, experimental, a Model Context Protocol server from an OpenAPI document; `server orpc` at the conformance bar.
- **`apigenie test`** speaks Kafka and AMQP (`KAFKA` and `AMQP` regions), GraphQL subscriptions over graphql-ws, gRPC client and bidirectional streams, MQTT 5 and mutual TLS.
- **Towards 1.0:** one table of exit statuses for the binaries, `formatVersion` in every JSON report with published JSON Schemas, a JSON Schema for `apigenie.yaml` behind `apigenie config`, `config check` and `config schema`, configuration discovery without `--config`, the [Compatibility](/docs/reference/cli/compatibility) page, and experimental labels on what is outside the coming promise.
- **Linting and diffing:** the OpenAPI format registry as the list of formats, with `schema-format-deprecated`, `schema-format-unknown` and a `hint` severity; `diff` knows sunset dates and no longer rates deprecating as breaking; `apigenie evolve plan OLD NEW`, experimental, plans an expand and contract migration.
- **Also:** `convert --from wsdl --to openapi31`, `i18n check` and `i18n sync`, OpenAPI formatting at every depth with layout options, Windows console colors, and a docs package published as `@mykulyak/apigenie-docs`.

The configuration check is the one to run first after upgrading. A file with a typo and a section that has no settings:

```text
$ apigenie config check apigenie.yaml
apigenie.yaml:5:7: /commands/lint/ruels: unknown property 'ruels'; did you mean 'rules'?
apigenie.yaml:7:5: /commands/bundle: unknown property 'bundle'
$ echo $?
2
```

0.9.0 skipped both lines without a word. 0.10.0 reports them with the line, the column and the JSON pointer, and every command that loads the file exits with 2 until they are fixed.

The JSON reports are objects now, with a version:

```text
$ apigenie lint --formatter json carpet-express.openapi.yaml | head -n 12
{
  "formatVersion": 1,
  "results": [
    {
      "filePath": "/work/carpet-express/carpet-express.openapi.yaml",
      "messages": [
        {
          "column": 1,
          "line": 1,
          "message": "Too many paths found (27), maximum number is 8",
          "ruleId": "paths-max-count",
          "severity": "warning"
```

What you change when you come from 0.9:

- `apigenie-mock` is `apigenie-server`, and its Docker image is `mykulyak/apigenie-server`. The old names keep working until 1.1 with a one-line notice on standard error: `apigenie-mock` is a symlink, and the `APIGENIE_MOCK_*` variables are read when the `APIGENIE_SERVER_*` variable of the same name is unset. The last `mykulyak/apigenie-mock` image only prints the new name and exits with 2. The `Server` and `Via` headers, the HAR creator and the contract report's `report` member say `apigenie-server`.
- One table of exit statuses for `apigenie`, `apigenie-generator` and `apigenie-server`: 0 success, 1 findings, 2 a usage, input or unexpected error, 3 and 4 the server's document and address errors, 5 a failed contract report. Errors that exited with 255 now exit with 2, so do unknown options and commands, missing files and configuration files that can't be parsed; `apigenie test` exits with 2 instead of 3 when a request file or the specification can't be read.
- `lint --formatter json` writes `{ "formatVersion": 1, "results": [...] }` and `diff --report detailed --formatter json` writes `{ "formatVersion": 1, "changes": [...] }`; both were bare arrays. Read `.results` and `.changes`.
- `diff` no longer rates deprecating as breaking. Setting `deprecated` announces a removal, and the removal is the breaking change, rated by `sunset_passed`. A gate that relied on the old rating sets `operation.deprecated: breaking` in `commands.diff.rules`.
- Seeded faker values change: the values of a `--seed` differ from 0.9.0's, usernames and emails are ASCII, and faker arguments are checked instead of clamped or ignored.
- `apigenie format` keeps JSON files JSON; set `format: yaml` to convert them. The OpenAPI format configuration is checked, and the `recommended` preset reaches nested schemas, callbacks and the objects of OpenAPI 3.2, so expect a one-time diff when reformatting with `extends: [recommended]`.
- The configuration file is validated against its JSON Schema when it is loaded, and `apigenie` and `apigenie-generator` find `apigenie.yaml` in the current directory or a parent up to the root of the repository. Pass `--no-config` to run with the defaults in a repository that has such a file.
- The npm project that `apigenie-generator docs` writes depends on `@mykulyak/apigenie-docs`. 0.9.0 wrote a package name that was never published, so `npm install` failed; replace the dependency or generate again.
- `apigenie test` connects with MQTT 5 and checks the MQTT 5 properties against the AsyncAPI MQTT bindings; a region that publishes to a channel whose binding states properties gives them with `# @property` lines or keeps 3.1.1 with `version: 3.1.1`.

## What is outside the promise

`apigenie-catalog`, `evolve plan`, `convert` and `server mcp` are experimental: their options and their output can change in a minor release, and their `--help` says so in the first line. Everything else in 0.10.0 is what 1.0 freezes, and the [Compatibility](/docs/reference/cli/compatibility) page is the list.

Upgrade, then run `apigenie config check` on your `apigenie.yaml`. What it lists is what the old version ignored.
