Public API Versioning and Stability

Every operation is under /v1. The version is in the path, so it is in every URL your code calls and every log line that records one. There is no version header to send.

What v1 promises

• Fields are only added. Inside v1, no field of a response is removed, renamed, given a different type or made nullable. A new field can appear in any response at any time, so ignore the fields you do not know.
• No request parameter becomes required. A request that works today keeps working.
• Every list of values is open. A report type, a plan, a script’s status: a new value is announced in the changelog at least 14 days before it first appears. Treat a value you do not know as you would other, rather than failing on it.
• Error codes are open too. Treat a code you do not know by its HTTP status (Errors).

For every operation not marked beta, these promises are checked rather than only written down: each change to the API is compared with the last released contract, and a removed field, a changed type or a new required parameter fails the build.

Beta operations

An operation is either beta or stable. A beta operation may also change in ways the promises above rule out, with a changelog entry and no notice period. An operation stays beta until customers outside HeaderHawk have used it, which is why every operation in the reference is beta today.

A new version

A change that v1 cannot absorb would be a new version, v2, served beside v1 rather than in place of it. From the day v2 is announced, v1 keeps working for at least twelve months, and every v1 response carries Deprecation and Sunset headers saying when it will stop.