# apigenie window

Source: https://api-genie.dev/docs/reference/cli/window
Part of the reference of [apigenie](https://api-genie.dev/docs/reference/cli.md).
Its other pages: [bundle](https://api-genie.dev/docs/reference/cli/bundle.md), [changelog](https://api-genie.dev/docs/reference/cli/changelog.md), [commands](https://api-genie.dev/docs/reference/cli/command-index.md), [completion](https://api-genie.dev/docs/reference/cli/completion.md), [config](https://api-genie.dev/docs/reference/cli/config.md), [convert](https://api-genie.dev/docs/reference/cli/convert.md), [credits](https://api-genie.dev/docs/reference/cli/credits.md), [diff](https://api-genie.dev/docs/reference/cli/diff.md), [evolve](https://api-genie.dev/docs/reference/cli/evolve.md), [format](https://api-genie.dev/docs/reference/cli/format.md), [i18n](https://api-genie.dev/docs/reference/cli/i18n.md), [init](https://api-genie.dev/docs/reference/cli/init.md), [license](https://api-genie.dev/docs/reference/cli/license.md), [lint](https://api-genie.dev/docs/reference/cli/lint.md), [overlay](https://api-genie.dev/docs/reference/cli/overlay.md), [run](https://api-genie.dev/docs/reference/cli/run.md), [test](https://api-genie.dev/docs/reference/cli/test.md).

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](#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](/docs/reference/cli#experimental-commands).

## Usage

```sh
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`](/docs/reference/cli/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](/docs/linter/openapi/rules/version-annotations-valid) 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`](/docs/linter/openapi/rules/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`](/docs/reference/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](/docs/reference/generator/client-fetch#version-aware-clients-experimental) and
[Python](/docs/reference/generator/client-python#version-aware-clients-experimental) 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`](/docs/reference/cli/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`](/docs/reference/cli/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`](/docs/reference/cli/diff#configuration). |
| `--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`](/docs/reference/cli#json-output) 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](/docs/reference/cli/compatibility)). With the global
[`--json`](/docs/reference/cli#json-output) 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](https://apigenie.pl/schemas/apigenie-window-report.json).

```json5
{
  "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:

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

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

```sh
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:

```sh
apigenie lint api.annotated.yaml
```
