Skip to content
PlusPanel

Versioning & deprecation

v1 is frozen at general availability

Section titled “v1 is frozen at general availability”

From general availability on, /api/v1 changes only in additive ways:

  • new operations;
  • new optional members in request bodies, new optional query parameters;
  • new members in responses;
  • new values of enumerations in responses;
  • new error codes for new situations.

Nothing that works today is removed, renamed or given a different meaning within v1. Until general availability, the API may still change; every such change is listed in the changelog.

What your client must do

Section titled “What your client must do”

To stay compatible with additive changes, a client must:

  • ignore unknown members in responses (do not fail on them, do not reject the object);
  • accept unknown enumeration values (treat an unknown status as “something else”, not as an error);
  • not depend on the order of members or of items, unless the reference says the order is defined;
  • branch on error code, not on human-readable text.

The client libraries and the CLI already behave this way.

Deprecation

Section titled “Deprecation”

When something has to go, it is first deprecated:

  • the operation is marked deprecated in the reference, with the date after which it may be removed (x-pluspanel-sunset);
  • its answers carry the Deprecation header (RFC 9745) and the Sunset header (RFC 8594) with that date, and a Link to this page with rel="deprecation";
  • the changelog names it and what replaces it.

The sunset date is at least 12 months after the announcement:

HTTP/1.1 200 OK
Deprecation: @1792368000
Sunset: Thu, 19 Oct 2028 00:00:00 GMT
Link: <https://pluspanel.net/docs/api/versioning/>; rel="deprecation"; type="text/html"

Log these headers when you see them, so a deprecation never takes you by surprise.

A new major version

Section titled “A new major version”

Removals happen only in a new major version, /api/v2. When v2 ships, v1 keeps running next to it for at least 12 months, so you can migrate at your own pace. The same API keys work on both.

Webhooks

Section titled “Webhooks”

Webhook payloads follow the same rules: new event types and new members in data may appear at any time; receivers must ignore what they do not know.