Versioning Policy

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

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. 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/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):

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. 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, reached from 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) 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: [email protected] — Subject: WHost API v1 compatibility regression.