API versioning
Before the public beta
Section titled “Before the public beta”- 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
DeprecationorSunsetheaders. 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.
Writing a tolerant client
Section titled “Writing a tolerant client”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.
Which version a server speaks
Section titled “Which version a server speaks”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.
The spec lint
Section titled “The spec lint”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.
API changelog
Section titled “API changelog”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.