No matching sections.

Versioning & deprecation

The version is an identity of the host, not a segment of the path: v2 is served at the root of api2.host-tracker.com, with no version prefix in the url. v2 is stable: it grows additively, and anything that would break a working client is published under a new hostname (or negotiated by a request header) - never by adding a path prefix to this one - together with a published sunset window, so a working client's urls never have to move for someone else's version bump.

v2 is stable

Every endpoint on the v2 API is generally available. There is no beta tier, no preview header and no per-endpoint stability flag - if it is in the reference, it is covered by this policy.

The published OpenAPI document at https://api2.host-tracker.com/openapi/v2.json is the machine-readable statement of the contract. It is generated from the running code, so it describes what the API actually does today - not what a hand-written document last remembered.

Changes we may make without a new version

These are not breaking changes, and a client must tolerate them:

• New endpoints.
• New optional request members and new optional query parameters. Existing requests keep working unchanged.
• New members in a response object. Ignore what you do not recognise.
• New values in an open vocabulary - a new monitor type, a new webhook event type, a new problem code. Handle the unknown case rather than assuming today's list is final.
• New response headers, and new members inside a problem's errors[] entries.
• Rewording of human-facing prose - a problem's title or detail, a summary, a description. These carry no data, which is exactly why you branch on code.
• Performance, ordering within an unordered collection, and the opaque contents of a cursor. Cursors and selection tokens are opaque by contract - never parse or construct one.

Changes that require a new version

These will never happen to the v2 API in place:

• Removing or renaming an endpoint, a field, a parameter or an enum value.
• Changing a field's type or units - including the meaning of an existing value.
• Making an optional request member required, or narrowing what an existing value accepts.
• Changing the HTTP status or the code an existing failure answers with.
• Changing the shape of the collection envelope, the problem document, or the job resource.

Write a tolerant client

Three habits make the additive rules free rather than risky:

• Ignore unknown response members instead of failing on them. If your JSON layer rejects unknown fields by default, turn that off for API responses.
• Have a default branch for unknown enum values and problem codes. A new code should be logged and surfaced, never swallowed.
• Treat cursors, selection tokens and delivery ids as opaque strings. Round-trip them; do not inspect, decode, shorten or generate them.

Note the asymmetry: we refuse unknown members on the way in - a misspelled request member is a 422, not a silent no-op - while asking you to tolerate new ones on the way out. That is deliberate: strictness on input catches your typos, tolerance on output lets the API grow without a coordinated release.

How a version ends

When a successor version exists and the v2 API is scheduled for retirement:

1. Announcement first, with a migration guide, before any header appears.
2. Affected responses begin carrying the standard Deprecation and Sunset headers. Sunset names the date after which the endpoint may stop answering, and a Link header with rel="deprecation" points at the migration guide.
3. The window is published and never shortened. The successor is generally available for the whole of it, so a migration is never a race.
4. Only after the sunset date does the old version stop answering.

An individual endpoint may also be deprecated inside a live version when a better one replaces it. It carries the same headers, keeps working for the published window, and is marked deprecated: true in the OpenAPI document - so a generated client warns at build time. Log these headers; they are the earliest possible warning you can get.

One date format, everywhere

Every timestamp on the v2 wire is an integer Unix seconds value, in both directions, on every endpoint and in every webhook envelope. Never an ISO 8601 string, never milliseconds.

"created": 1785712608
"resetAt": 1785755142
"occurredAt": 1785672303

Date ranges are always spelled from and to - one vocabulary across the whole surface. The one exception to the seconds rule is a handful of duration fields whose name ends in Ms (for example a delivery's latencyMs): those are elapsed milliseconds, not timestamps. A field naming a point in time is always seconds.