API stability

The API you build against today keeps working. This page says what we may change without notice, what we will not change without telling you first, and how you will be told.

Versioning

Every path starts with /v1. A v2 would be a new prefix served beside v1, not a replacement for it, and is not planned. The published OpenAPI document describes v1 exactly as it is deployed.

Changes we make without notice

These are additive and a well-behaved client keeps working through them:

• new operations and new paths;
• new optional request fields and query parameters;
• new fields in responses;
• new values in response enums (a status, an event kind) — treat a value you do not recognise as unknown rather than failing on it;
• new error type URIs, and a more helpful detail on an existing one;
• new response headers.

Breaking changes, and the notice you get

Removing or renaming an operation, field or parameter, changing a field’s type or meaning, making something optional required, or refusing what was accepted before is a breaking change. We make one only after:

1. Deprecation. The old behaviour stays, is marked deprecated in the OpenAPI document, and every response from it carries Deprecation: @<unix time> and Sunset: <HTTP date> (RFC 9745, RFC 8594) with a Link to the changelog entry.
2. Notice. At least six months between the deprecation and the sunset, announced in the API changelog and emailed to the owners of every organization with an API token that called it in the last 90 days.
3. Sunset. On the sunset date it goes. Calls then answer 410 Gone.

A change we have to make for security — closing a hole — may come with less notice. We will say so in the changelog and email the affected owners.

What is not covered

• Endpoints the portal uses that are not in the OpenAPI document (there are none today; if there ever are, they are not part of the API).
• Error detail text: it is for people, and it changes. Match on type.
• The order of fields, of array items not documented as ordered, and of headers.
• Rate limits, which may be raised at any time and lowered only with notice. See Rate limits.

The changelog

Every change to the OpenAPI document is listed, newest first, in the API changelog, with whether it is additive or a deprecation. Each version of the document is kept at https://docs.updawg.net/openapi/<date>.json, so a client can pin one and diff it against the next.