Versioning and deprecation
The API is versioned in its path: /v1. Within a version WatchTower15 only adds.
What may be added to /v1
Section titled “What may be added to /v1”- New operations.
- New optional parameters.
- New fields in answers.
- New values in a field that lists values (an enum).
Write your client to ignore fields it does not know, and to treat an enum as an open set: an unknown value is not an error.
What is a breaking change
Section titled “What is a breaking change”Removing an operation, a field or an enum value, making an optional parameter required, or
changing what a field means. WatchTower15 does not make these inside /v1. They arrive as a
new operation or as /v2, and the old one keeps working for a stated period.
Retirement
Section titled “Retirement”When an operation or version is to be retired, its answers carry a Deprecation header from the
day it is announced and a Sunset header with the date it stops. Watch for them in your client’s
logs.
The reference always shows the current contract.