# Versioning and deprecation

The InfraNest API has one version, and it changes by adding. There is no `/v1` in the address and no version
header to send: a script written today keeps working, and anything that would break it is announced months ahead.

## What changes without notice

- **New endpoints, new fields in a response, new optional parameters.** Write clients that ignore fields they do not
  know, and do not fail on an unknown key.
- **New error codes.** A new refusal gets a new `code`; existing codes never change. Treat a code you do not know by
  its HTTP status.
- **New values in a list of options** (a monitor type, an event name). Handle an unknown value without failing.
- **Wording.** `message` and `hint` in an error, and descriptions in the reference, may be reworded. Branch on
  `code`, never on text.

## What gets six months' notice

- **Removing or renaming** an endpoint, a field or a parameter.
- **Changing what a field means**, including its type.

Each is announced in the [changelog](changelog.md) at least six months before it takes effect, with the date it
takes effect and what to use instead. Until that date both the old and the new way work.

## How changes are announced

- **The [changelog](changelog.md)**, every change, each dated, newest first.
- **The RSS feed** at [`/changelog.xml`](/changelog.xml), for a feed reader or a chat channel.
- **[infranest-openapi](https://github.com/InfraNest-Infrastructure-Organized/infranest-openapi)**, where every
  published version of `openapi.json` is a dated release with what was added, removed and changed. Watch its
  releases to be told.

## `Deprecation` and `Sunset` headers

The API does not send these headers yet. When it does, a response from something on its way out will carry
`Deprecation` (when it was announced), `Sunset` (the date it stops working) and a `Link` to its changelog entry, so
a client can log a warning without anyone reading the changelog. Until then, the changelog and its feed are where
a deprecation is announced.

## Stable things to build on

- **Error codes** — see [Errors](errors.md).
- **Scopes** — see [Scopes](scopes.md).
- **Webhook envelopes** — `event`, `created_at` and `data`, see [Webhooks](webhooks.md).