Skip to content
Log inDashboard

API versioning

  • The API changes without a deprecation period. Endpoints and fields are added, changed, renamed and removed as the product needs, with no notice period and no Deprecation or Sunset headers. The dashboard and opdns’s own clients change with the API in the same release.
  • Every change is versioned and listed. The specification’s version changes with every change to it, every response names the version it speaks, and the changelog says what changed in each version, removals included.

If you script against the API before the beta, pin nothing to it you cannot change quickly, and read the changelog when the version in X-Opdns-Api-Version changes.

The API’s contract is its OpenAPI document, /v1/openapi.yaml, which the reference is generated from. The policy on this page is the one written in that document’s info.description.

Every route is under /v1. Most changes add something: new endpoints, new optional request fields, new response fields, new enum values, new columns in query results. So that these never break you, a client should:

  • ignore response fields it does not know;
  • treat an enum value it does not know as “other”;
  • read query results by column name, never by position.

The document’s info.version is the contract’s version. It changes with every change to the document: the minor version for any change to the contract (an addition, a change or a removal), the patch version for changes to descriptions, summaries and examples only. A few early additions shipped as patch versions (0.5.2, 0.6.1, 0.6.2); that no longer happens. The current version is 0.56.0.

Every API response carries it:

X-Opdns-Api-Version: 0.56.0

It is also the api_version field of GET /v1/meta. The header always names the document the server was built with, and opdns cannot release a changed document without a new version: a contract change shipped as a patch version, or a wording change shipped as a minor one, is refused.

Every change to the document is checked against a strict set of OpenAPI rules. Every operation has an operationId and a description, every tag a description, every error response is an application/problem+json Problem with an example, and every example validates against its schema. This is why the reference has a description for every operation and an example for every error.

Every version of the document is listed in the API changelog, newest first: a summary of what a client should know, and the list of what changed in the document (operations, who may call them, fields, parameters, responses, enum values and problem codes), generated from the document’s own history so nothing is left out. Removals and other changes that need a client to change are called out there.