# Compatibility Source: https://apigenie.pl/techdocs/reference/cli-compatibility Scripts, CI jobs, Dockerfiles and dashboards call API Genie and read what it writes. This page says what they can rely on from one release to the next. From 1.0.0, `apigenie`, `apigenie-generator` and `apigenie-server` follow [semantic versioning](https://semver.org/spec/v2.0.0.html) for everything listed under [What the promise covers](#what-the-promise-covers): - a **patch** release (1.0.1) fixes bugs and changes nothing listed there; - a **minor** release (1.1.0) adds commands, options, settings and members, and may [deprecate](#deprecation) something, but keeps it working; - only a **major** release (2.0.0) removes or changes what is listed there. The fourth binary, [`apigenie-catalog`](/techdocs/reference/cli-catalog), is experimental as a whole (see [What it doesn't cover](#what-it-doesnt-cover)) until it becomes stable. Versions below 1.0.0 make no such promise: the [changelog](https://github.com/mykulyak/api-genie/blob/main/CHANGELOG.md) lists what each one broke under "Upgrading". ## What the promise covers - **Command names and subcommands** of the three binaries: the commands of [`apigenie`](/techdocs/reference/cli-overview), the targets of [`apigenie-generator`](/techdocs/reference/cli-generate) (`client fetch`, `server spring`, ...), and [`apigenie-server`](/techdocs/reference/cli-server). - **Option names and their meaning**: an option keeps its name, its short form, the values it accepts and what it does. A new option, or a new accepted value, is a minor change. - **Configuration keys and their schema**: the keys of [`apigenie.yaml`](/techdocs/reference/cli-configuration) and `apigenie-server.yaml`, their types and defaults, as the JSON Schema of each release (`https://apigenie.pl/schemas/apigenie-config/.json`) describes them. A file that is valid for 1.x stays valid for every later 1.y. - **Environment variables**: `APIGENIE_TELEMETRY_FILE`, the `APIGENIE_SERVER_*` variables of [`apigenie-server`](/techdocs/reference/cli-server) (`HOST`, `PORT`, `TLS_CERT`, `TLS_KEY`, `CA_CERT`, `INSECURE`, `PROXY_TO`, `REPORT`, `REPORT_JUNIT`, `RECORD_DIR`, `RECORD_HAR`, `STUBS`, `PROTO_PATH`, `MQTT_PORT`), and `APIGENIE_MQTT_USERNAME` and `APIGENIE_MQTT_PASSWORD`. - **Exit statuses**: the [table](/techdocs/reference/cli-overview#exit-status) shared by the three binaries. - **The `formatVersion` of each JSON report**: see [Versioned JSON outputs](#versioned-json-outputs) below. - **The docs bundle contract**: the layout of the bundle and its manifest `apigenie-docs.json` ([`apigenie-generator docs`](/techdocs/reference/cli-generate_docs)), whose `apigenieDocs` and `formatVersion` say which `@mykulyak/apigenie-docs` versions can build it. - **The admin API of `apigenie-server`**: the paths and methods under `/__apigenie` listed in [Admin API](/techdocs/reference/cli-server#admin-api), and the JSON they answer with. New paths and new members are minor changes. - **The `x-apigenie-*` extensions the tools read**: `x-apigenie-lint-disable` ([lint](/techdocs/reference/cli-lint)), `x-apigenie-mock` and `x-apigenie-mock-faker` ([server](/techdocs/reference/cli-server#scenarios-and-extensions)), and the `codegen` members of `x-apigenie` (`name`, `action-name`, `controller-name`, `disabled`) that the generators read. ## What it doesn't cover - **The inside of generated code.** A generator keeps the options on its page and the shape of what it generates for your API: the names of the types, functions and routes. The generated files' layout, formatting, private helpers and comments, and the versions of the libraries they depend on, can change in a minor release, when a generator is fixed or improved. Commit generated code, or pin the API Genie version that generates it. - **Log and message text**: warnings, errors, progress lines and the text formatters (`stylish`, `compact`, `unix`, `visualstudio`, `html`, and the text and Markdown output of `diff` and `changelog`). Read the JSON reports, SARIF, checkstyle, TAP or JUnit XML instead. - **The wording of `--help`.** - **Experimental commands**: they say "(experimental, outside the 1.0 compatibility promise)" in their `--help` and on the first line they print, and the CLI overview lists them under [Experimental commands](/techdocs/reference/cli-overview#experimental-commands). Their options and output can change, or they can go away, in a minor release. When one becomes stable, the promise covers it from that release on. - **What a release fixes**: when API Genie accepted a document it shouldn't have, or reported a finding it shouldn't have, a minor or patch release can correct it, even though a script sees a different result. New lint rules in the built-in rulesets arrive in minor releases. ## Deprecation Something covered by the promise is removed or changed in two steps: 1. A **minor release announces it**: the changelog lists it under "Deprecated" with what to use instead, its reference page says so, and using it prints a one-line warning on the standard error (the standard output stays as it was). 2. It is **removed no earlier than the next minor release**, and only in a major release once 1.0 is out. The changelog lists the removal under "Removed" and "Upgrading". The rename of `apigenie-mock` to `apigenie-server` follows these rules: the old names print a notice and keep working until 1.1 (see [Deprecated names](/techdocs/reference/cli-server#deprecated-names)). ## Versions `apigenie`, `apigenie-generator`, `apigenie-server` and `apigenie-catalog` are built, released and installed together, always with the same version. `apigenie --version` prints its version on the first line and the versions of the others below it, so a mismatch shows. The [Docker images](/downloads), the npm package and the Homebrew formula carry that version too. The **VS Code extension**, the **desktop editor** and the **docs package** (`@mykulyak/apigenie-docs`) are released on their own, each with its own version and changelog. This page covers the four binaries; the extension and the editor follow semantic versioning of their own version. ## Versioned JSON outputs Every JSON report of the CLI and the server has a top-level `formatVersion` member, an integer that started at 1, and a JSON Schema published on this site: | Output | Schema | | ------ | ------ | | [`apigenie lint --formatter json`](/techdocs/reference/cli-lint) | [apigenie-lint-report.json](https://apigenie.pl/schemas/apigenie-lint-report.json) | | [`apigenie diff --formatter json`](/techdocs/reference/cli-diff) (`status`, `changelog` and `detailed` reports) | [apigenie-diff-report.json](https://apigenie.pl/schemas/apigenie-diff-report.json) | | [`apigenie changelog --formatter json`](/techdocs/reference/cli-changelog) | [apigenie-changelog-report.json](https://apigenie.pl/schemas/apigenie-changelog-report.json) | | [`apigenie-catalog list --json`](/techdocs/reference/cli-catalog) | [apigenie-catalog-report.json](https://apigenie.pl/schemas/apigenie-catalog-report.json) | | [`apigenie test --report`](/techdocs/reference/cli-test) | [apigenie-test-report.json](https://apigenie.pl/schemas/apigenie-test-report.json) | | [`apigenie-server --report`, `GET /__apigenie/contract`, `GET /__apigenie/contract.json`](/techdocs/reference/cli-server) | [apigenie-contract-report.json](https://apigenie.pl/schemas/apigenie-contract-report.json) | | [`apigenie-docs.json`](/techdocs/reference/cli-generate_docs), the manifest of a docs bundle | [apigenie-docs-manifest.json](https://apigenie.pl/schemas/apigenie-docs-manifest.json) | The `apigenie test --formatter json` stream carries `formatVersion` in its `summary` line. The contract and test reports also have `version`, the former name of `formatVersion`; it is deprecated and will be removed in the next release. **Adding fields keeps the version; removing or changing one bumps it.** A new member, or a new value of a member documented as open (such as a new change type), keeps `formatVersion`, so readers should ignore members they don't know. Removing a member, renaming it, or changing its type or meaning increments `formatVersion`, and the schema of the new version is published next to the old one. After 1.0, a new `formatVersion` is a breaking change and waits for a major release. ### External formats SARIF, JUnit XML, checkstyle and TAP are defined elsewhere and keep their own versions: SARIF output says `"version": "2.1.0"`, and the others follow the formats their tools read. ## Reporting a break If a minor or patch release breaks something this page covers, it's a bug. Open an issue at [github.com/mykulyak/api-genie/issues](https://github.com/mykulyak/api-genie/issues) with the two versions (`apigenie --version`), the command line, and what it did before and after. The fix is a patch release that brings the old behaviour back. If something you rely on isn't listed here, ask for it in an issue too.