Versioning

The version is in the path: every endpoint is under /v1. That prefix is a promise to people who write code against it.

The /v1 promise

Within /v1, changes are additive only. We may:

• add an endpoint;
• add a field to a response;
• add an optional query parameter;
• add a value to a vocabulary — a new cause category, a new utility, a new network;
• reword an error message (never its code).

We will not, within /v1:

• remove or rename a field, a parameter or an endpoint;
• change what a field means, or its type;
• change a field from never-null to sometimes-null;
• make an optional parameter required;
• change an error code.

Anything that would break the promise is a /v2, published beside /v1 rather than in place of it, and announced in the changelog first.

Writing a client that keeps working

• Ignore fields you do not know. A new field is not a breaking change, so do not fail on one. Strict schema validation of responses is the most common way to turn an addition into an outage.
• Expect new values in vocabularies. Handle a cause.category, utility or network.id you have not seen before — treat an unknown category as other, for example, rather than throwing.
• Switch on error.code, never error.message.
• Treat ids and cursors as opaque. An outage id is an integer that is stable for the outage's whole life; it carries no meaning beyond that.

The contract is published

The full contract is published as OpenAPI 3.1 at GET /v1/openapi.json, which needs no key. It is generated from the same definitions that validate every request and shape every response, so it cannot describe a field the server does not send. This reference is built from it.

Every change is listed in the changelog.