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 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, every change, each dated, newest first.
• The RSS feed at /changelog.xml, for a feed reader or a chat channel.
• 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.
• Scopes — see Scopes.
• Webhook envelopes — event, created_at and data, see Webhooks.