API versioning + deprecation

The Wholisphere API is versioned per surface, not per route. The current version is v1. Every response includes the current version in a header so clients can verify what they’re talking to:

x-wholisphere-api-version: v1

Compatibility promise

Within a major version we will:

• Add new fields, routes, headers, query params, and event kinds at any time.
• Never remove existing fields, routes, headers, or event kinds without a deprecation cycle.
• Never change the type or semantics of an existing field without a deprecation cycle.

A “deprecation cycle” is at least 12 months between the first Deprecation: true header response and the route returning 410 Gone.

How deprecations are signaled

When a route is deprecated, every response on that route includes:

Deprecation: true
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Link: </v1/replacement>; rel="successor-version"

These are the standard headers from RFC 8594 and the Deprecation header draft.

We recommend you:

1. Log + alert in CI any time a Deprecation header appears on a route you call.
2. Migrate to the successor-version URL well before Sunset.
3. Treat 410 Gone responses as a signal to upgrade your client immediately.

Major version bumps

A v2 will arrive only when we need a breaking change that can’t be modeled as an additive deprecation cycle. v2 will live at /v2/... paths side-by-side with v1 for at least 12 months. The x-wholisphere-api-version header lets you detect which version a route is part of without inspecting the URL.

Currently deprecated routes

None. When deprecations land they will be listed here with their Sunset date and replacement.