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 for everything listed under 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 something, but keeps it working;
  • only a major release (2.0.0) removes or changes what is listed there.

The fourth binary, apigenie-catalog, is experimental as a whole (see What it doesn’t cover) until it becomes stable.

Versions below 1.0.0 make no such promise: the changelog lists what each one broke under “Upgrading”.

What the promise covers

  • Command names and subcommands of the three binaries: the commands of apigenie, the targets of apigenie-generator (client fetch, server spring, …), and apigenie-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 and apigenie-server.yaml, their types and defaults, as the JSON Schema of each release (https://apigenie.pl/schemas/apigenie-config/<version>.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 (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 shared by the three binaries.
  • The formatVersion of each JSON report: see Versioned JSON outputs below.
  • The docs bundle contract: the layout of the bundle and its manifest apigenie-docs.json (apigenie-generator 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, 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), x-apigenie-mock and x-apigenie-mock-faker (server), 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. 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).

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, 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 apigenie-lint-report.json
apigenie diff --formatter json (status, changelog and detailed reports) apigenie-diff-report.json
apigenie changelog --formatter json apigenie-changelog-report.json
apigenie-catalog list --json apigenie-catalog-report.json
apigenie test --report apigenie-test-report.json
apigenie-server --report, GET /__apigenie/contract, GET /__apigenie/contract.json apigenie-contract-report.json
apigenie-docs.json, the manifest of a docs bundle 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 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.