apigenie window

Finds the support window of an OpenAPI document (the versions since its last breaking change) and writes the version annotations that let a client built from the newest version talk to a server of any version of the window. It then proves them by projecting the document back to each version.

(experimental, outside the 1.0 compatibility promise) window, since 1.0.0, is the first version of version-aware clients: the annotations, the rules that end the window and the report can still change, and the client generators read only part of the annotations (see What the clients read). It says so in its --help and on the first line it prints, on the standard error. See the experimental commands.

Usage

apigenie window [OPTIONS] SPEC

Description

A server of version 1.2.0 rejects a request with a property added in 1.3.0, and a client built from 1.3.0 doesn’t know that the property is new. window reads the history of SPEC, its release tags by default, and walks back from the newest version. Every pair of consecutive versions is compared as diff compares them. The window ends at the first pair with a breaking change, or with a change that no annotation can describe to a client:

End The window starts at the newer version of the pair because
breaking the change into it breaks clients
blocking a request change an older server would reject and no annotation describes: a required request property removed, a constraint widened (with a configuration that rates it non-breaking), a changed type, a changed security scheme, … A change of title, description, deprecated, example, examples or externalDocs doesn’t count
same-version the older revision has the same info.version, and they differ in what the annotations say: a server can’t tell them apart
no-version the older revision has no info.version
history-start the history has no older version

Then window writes the annotations of every change of the window into SPEC, and info.x-apigenie-versions, the versions of the window from oldest to newest, after info.version. The document keeps its comments; YAML is written in block style. An operation of a path item that SPEC takes from components.pathItems is annotated there. An annotation of SPEC whose version its info.x-apigenie-versions listed, but the window no longer has, is older than the window: it is taken out, and the report lists it under “Dropped”.

Before it writes anything, window checks its own work. It projects the annotated document to the version of every revision of the window and compares the projection with that revision. The check fails if a client of the projection would break, or if an annotated element differs: one is there that shouldn’t be (an annotation missing, or too old), one is missing (an annotation too new), or a parameter is required when it shouldn’t be. It also checks the annotated document as the lint rule does: a version the generators can’t place fails the run too. On a failure window names the version and the element, writes nothing and exits with status 2.

The annotations

Each annotation names the version in which the change arrived. Two versions listed in info.x-apigenie-versions are ordered by their position there; two semantic versions by SemVer precedence (a v prefix and build metadata don’t count); otherwise a version that isn’t listed is newer than a listed one. An annotation can use a listed version, or a semantic version when the document has no list. On a parameter used through $ref, the annotations go next to the $ref and apply to that use only. The version-annotations-valid lint rule checks annotations written by hand.

Annotation On Means
info.x-apigenie-versions info The versions of the window, oldest first
info.x-apigenie-version-header info The response header that carries the server’s version (see apigenie-server)
x-apigenie-added: VERSION operation, parameter, property, request body, request media type, security scheme Absent before VERSION
x-apigenie-removed: VERSION the same Gone from VERSION; a version after info.version announces a removal
x-apigenie-made-optional: VERSION parameter, property Required before VERSION
x-apigenie-made-required: VERSION parameter, property Optional before VERSION
x-apigenie-renamed-from: {version, name} parameter, property Called name before version
x-apigenie-type-changed-from: {version, schema} parameter, property Had the schema schema before version
x-apigenie-enum-added: {VALUE: VERSION} schema with enum VALUE is absent from the enum before VERSION

A new alternative of a security requirement is annotated on its scheme under components.securitySchemes, because a security requirement object can’t carry extensions. Response changes need no annotation: a client ignores what it doesn’t read.

What the clients read

The TypeScript fetch and Python client generators read part of what window writes:

Annotation Read on Ignored on
x-apigenie-added operations, parameters, schema properties (optional in the types; only the top-level properties of a request body are gated) request bodies, request media types, security schemes
x-apigenie-made-optional request parameters, top-level request properties nested request properties
x-apigenie-made-required response properties request parameters and properties
x-apigenie-enum-added the schemas of parameters and top-level request properties nested request properties
x-apigenie-removed, x-apigenie-renamed-from, x-apigenie-type-changed-from everywhere

A client of the newest version can still send what an ignored annotation gates to an older server.

History

By default the history is the release tags that match --tags and change SPEC, as for changelog; --history commits takes every commit that changes it. When SPEC in the working tree differs from its last revision, the working tree is the newest version (SPEC (working tree)). A revision that can’t be read is skipped with a warning. --history-spec replaces the git history with files.

SPEC must be self-contained: run bundle first if it refers to other files.

Options

Option Description
--history HISTORY Where the versions come from: tags (default), the release tags, or commits, every commit that changes SPEC.
--tags PATTERN The glob pattern of the release tags, for example v*. Defaults to *.
--from REV The oldest revision to consider, for example a tag. Defaults to the whole history.
--history-spec FILE A version of the document, instead of the git history; repeat it, oldest first. SPEC is the newest version. Can’t be combined with --history, --tags or --from.
--git GIT The git program. Defaults to git.
--config FILE, --no-config The configuration file whose commands.diff block rates the changes, as for diff.
--out FILE Where the annotated document goes, in the format of SPEC. Defaults to the standard output, and the report then goes to the standard error. --json needs it.
--format FORMAT The report: text (default) or json.

JSON output

With --format json the report is an object whose formatVersion member is the version of the format, changed only when a member is removed or changes meaning (see Compatibility). With the global --json the report is the only thing on the standard output, whatever --format says. --json therefore needs --out: without it window prints the status and exits with 2. Its JSON Schema is apigenie-window-report.json.

{
  "formatVersion": 1,
  "result": "annotated",        // or "failed": a self-check failed, nothing was written
  "document": "api.yaml",
  "output": "annotated.yaml",   // "" for the standard output, null when nothing was written
  "window": {
    "from": { "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" },
    "to": { "label": "api.yaml (working tree)", "id": "api.yaml", "version": "1.3.0" },
    "versions": ["1.1.0", "1.2.0", "1.3.0"],
    "revisions": [{ "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" }, "..."]
  },
  "end": {
    "reason": "breaking",       // or blocking, same-version, no-version, history-start
    "before": { "label": "v1.0.0", "id": "91ab...", "version": "1.0.0" },
    "changes": [{ "location": "/paths/~1shipments~1{id}/get/responses/200/...", "change": "..." }]
  },
  "dropped": [],                // annotations of SPEC older than the window, taken out
  "annotationIssues": [],       // what the lint rule reports on the result; "fails": true fails the run
  "annotations": [
    { "annotation": "x-apigenie-added", "element": "#/paths/~1shipments~1{id}~1hold/post", "version": "1.2.0", "location": "..." },
    { "annotation": "x-apigenie-enum-added", "element": "#/components/schemas/ServiceLevel", "version": "1.3.0", "value": "same_day", "location": "..." }
  ],
  "checks": [{ "revision": { "label": "v1.1.0", "id": "4f2c...", "version": "1.1.0" }, "status": "ok", "differences": [] }]
}

Exit status

Status Meaning
0 The window was found, every self-check passed, and the annotated document was written
2 Invalid options, a file that can’t be read or isn’t a self-contained OpenAPI 3.x document, no info.version, a git error, an invalid configuration, a failed self-check, or an annotation version the generators can’t place (nothing written)

Examples

Annotate the document of the working tree from its v* release tags:

apigenie window api.yaml --tags 'v*' --out api.annotated.yaml

Annotate from released files and print a JSON report for a pipeline:

apigenie window api.yaml --history-spec api.1.1.yaml --history-spec api.1.2.yaml \
  --out api.annotated.yaml --format json

Check annotations written by hand:

apigenie lint api.annotated.yaml
Last updated on View as Markdown
Was this helpful?