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.
Two binaries, apigenie-catalog and
apigenie-mcp, are experimental as a whole (see
What it doesn’t cover) until they become 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 ofapigenie-generator(client fetch,server spring, …), andapigenie-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.yamlandapigenie-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, theAPIGENIE_SERVER_*variables ofapigenie-server(HOST,PORT,TLS_CERT,TLS_KEY,CA_CERT,INSECURE,PROXY_TO,REPORT,REPORT_JUNIT,RECORD_DIR,RECORD_HAR,STUBS,PROTO_PATH,MQTT_PORT), andAPIGENIE_MQTT_USERNAMEandAPIGENIE_MQTT_PASSWORD. - Exit statuses: the table shared by the three binaries.
- The
formatVersionof 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), whoseapigenieDocsandformatVersionsay which@mykulyak/apigenie-docsversions can build it. - The admin API of
apigenie-server: the paths and methods under/__apigenielisted 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-mockandx-apigenie-mock-faker(server), and thecodegenmembers ofx-apigenie(name,action-name,controller-name,disabled) that the generators read (Specification extensions lists them with the others).
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 ofdiffandchangelog). 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
--helpand 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.apigenie-mcp, whose standard output carries the protocol, says it only in its--help. When one becomes stable, the promise covers it from that release on.
- Experimental commands: they say “(experimental, outside the 1.0 compatibility promise)” in
their
- 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:
- 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).
- 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 apigenie-mock
command, deprecated in 0.10, was removed in 1.0, and the other old names print a notice and keep
working until 1.1 (see Deprecated names).
Versions
apigenie, apigenie-generator, apigenie-server, apigenie-catalog and (since 0.12.0)
apigenie-mcp 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.
Since 0.12.0 the desktop editor is released with the five binaries, at their version. The
VS Code extension and the docs package (@mykulyak/apigenie-docs) are released on their
own, each with its own version and changelog. This page covers the five binaries. The desktop editor
shares their version but is not part of the promise above; the extension follows semantic
versioning of its 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:
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.