Skip to content
Dials Docs

Versioning and deprecation

The current version is v1, at https://api.dials.co/v1. Build against the prefixed URL.

The same paths also answer without the prefix (https://api.dials.co/models) as a permanent alias for whatever the current version happens to be. That is convenient for a quick curl and wrong to pin an integration to, because it moves when the current version moves.

Inside a version

  • Changes are additive only: new endpoints, new optional parameters, new fields on a response.
  • A field is never removed, renamed or retyped, and a code in error is never repurposed.
  • A breaking change ships as a new prefix (/v2), served alongside the old one.

When a version winds down

Every response the deprecated version serves carries:

  • Deprecation: true (RFC 9745)
  • Sunset: <HTTP-date> (RFC 8594), the date after which it stops answering, never less than six months out
  • a Link header with rel="successor-version" pointing at the replacement

X-API-Version names the serving version on every response, deprecated or not, so a client can assert it is talking to what it thinks it is.