# Versioning Policy

> **Audience:** third-party integrators (billing systems, custom panels, monitoring tools).

WHost API stability promises are codified below. This document is the
authoritative reference — implementation behaviour follows what is written
here, not the other way around.

---

## 1. Version Prefix

Every endpoint is mounted under `/api/vN/` where `N` is a major version.
Today only `v1` exists. A request to a path without a version prefix is a
client bug and returns `404`. (The schema also lists `/health`, the agent's
local liveness probe; the web server in front of the agent does not publish it.)

```
GET /api/v1/accounts/{username}        ✔ canonical
GET /accounts/{username}                ✘ 404
```

## 2. Stability of `v1`

**`v1` is stable forever.** Once a v1 endpoint, request field, or response
field ships in a release, it is permanent for the lifetime of v1.

Allowed in v1:

- Adding new endpoints (additive)
- Adding new **optional** request fields
- Adding new fields to response payloads (clients must ignore unknown fields)
- Fixing bugs that bring behaviour into line with documented contract

**Not allowed** in v1:

- Removing an endpoint
- Removing or renaming a request/response field
- Changing the type of a field
- Tightening validation (rejecting input that was previously accepted)
- Changing the HTTP status code returned by a documented success case

If any of the above becomes necessary, it is shipped as `v2`, not as a v1
modification.

## 3. Major Version Bumps (`v2`, `v3`, …)

A new major version is introduced as a **parallel** path prefix
(`/api/v2/`). The agent serves both versions side-by-side for the full
deprecation window — no client is forced to migrate on a release.

No `v2` has been announced and nothing in `v1` is deprecated: the phases below
describe what happens once a new major version is announced.

### Announcement timeline

| Phase | Duration | What happens |
|-------|----------|--------------|
| Beta | ≥ 3 months | Endpoints available under `/api/v2-beta/`; subject to change |
| Public release | T = 0 | Endpoints stable under `/api/v2/`; both v1 and v2 reachable |
| Deprecation window | ≥ 12 months from T | v1 still works; `Deprecation: true` and `Sunset: <HTTP-date>` headers returned on every v1 response |
| Sunset | After deprecation window | v1 endpoints return `410 Gone` |

The minimum window between announcing `v2` and removing `v1` is **15 months**
(3 months beta + 12 months deprecation).

## 4. Minor and Patch Versions

The agent's `__version__` (e.g. `1.0.0-beta.1`, `1.0.0`) follows [Semantic Versioning](https://semver.org/).
The public release line starts at `1.0.0-beta.1`; builds before it carried internal numbers that were never
published. A pre-release carries its tag in the packaged version itself (`1.0.0-beta.1`), so an
installation on a beta orders below the release it matures into and is offered that release; the
update package, the installer's `WHOST_VERSION` and the panel's `package.json` carry the same string.
Beta is the only pre-release kind WHost is published under (`1.0.0-beta.9` < `1.0.0-beta.10` < `1.0.0`).

- **Patch** (`z`) — bug fixes only; no API surface change.
- **Minor** (`y`) — additive API changes within the current major (new
  endpoint, new optional field, new response field).
- **Major** (`x`) — the only kind of release that may bring a new `/api/vN/`
  prefix; the old prefix is retained per §3.

The release number and the API prefix are counted separately: the `1.x` agent
serves `v1`. The betas of a line (`1.0.0-beta.N`) are previews of one release
and can carry fixes and additions alike; the kinds above describe the steps
between releases.

## 5. Deprecation Headers

No response carries these headers today: nothing in `v1` is deprecated. When
v1 enters the deprecation window, every v1 response will carry them (the date
below is an example; no sunset date has been set):

```http
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Tue, 30 Sep 2027 00:00:00 GMT
Link: </api/v2/accounts/{username}>; rel="successor-version"
```

The `Link` header will point to the equivalent v2 endpoint when one exists.

Individual endpoints within a major version may also be deprecated without a
full version bump. In that case the same `Deprecation` / `Sunset` headers will
be sent on that endpoint only, while the rest of the version stays
warning-free.

## 6. Field-Level Removal Within a Major Version

A field may be marked deprecated within a major version (still returned, but
flagged). No field is deprecated today; when one is, the agent will send a
warning such as (the field names are an illustration):

```http
Warning: 299 - "Field 'legacy_quota_bytes' is deprecated; use 'quota_bytes' instead"
```

The field continues to be populated for the full §3 deprecation window before
becoming `null` and finally removed in the next major version.

## 7. Breaking Bugfix Exception

If a documented v1 behaviour is found to be **insecure** (e.g. an
authorization check missing on a specific code path), the fix is shipped as
a v1 patch even if it changes observable behaviour. Such fixes are:

- Listed in the release notes under the Security heading
- Announced 7 days before release where operationally feasible
- Accompanied by a workaround for impacted integrators

This exception applies only to fixes that close a security or data-integrity
risk. Pure UX preferences do not qualify.

## 8. OpenAPI Schema Source of Truth

The OpenAPI 3.1 schema at `GET /api/v1/openapi.json` (a signed request or an
admin session; there is no anonymous access) is the canonical machine
description of v1; a copy is published beside this document as
[`openapi.json`](openapi.json). If a discrepancy exists between this document
and the schema, the schema wins — report it as described in §10. The
per-endpoint reference ([`api-reference-generated.md`](api-reference-generated.md),
reached from [`api-reference.md`](api-reference.md)) is generated from the schema.

## 9. SDK Compatibility Promise

The PHP SDK is the only official SDK today; it is a download from this site
(see [the PHP SDK page](sdk-php.md)) and targets the `v1` API. Its version
number is its own: while it is `0.x` (today `0.1.1`), a minor release may
change behaviour and its `CHANGELOG.md` says so. From `1.0.0` on, one SDK
major version targets one API major version: `1.x.y` works against `v1`;
if a `v2` API ships, a new SDK major follows and the `1.x` line keeps
receiving fixes for the v1 deprecation window. Python and Node.js SDKs are
planned, not released.

## 10. How to Report a Compatibility Issue

If you have integrated against `v1` and an agent release breaks your
integration, that is a bug in WHost — not in your code. Open a ticket with:

1. Agent version (`GET /api/v1/system/update/status` → `current_version`)
2. Endpoint + request body that previously worked
3. Observed response (status code + body)
4. Expected response

Contact: `hello@wisecp.com` — Subject: `WHost API v1 compatibility regression`.