API notice1 min readBrouillon: no results reported
API v1: how we announce a meaning change
Deprecation and Sunset headers, the email we send first, and what counts as a change in meaning.
Integrators build bots and programmes on top of the Agronomist API. A change in what a field means can break them as surely as a change in its shape. This notice describes how we will announce such changes.
Every response says which version it is
X-DeepLeaf-Api-Version: v1
Link: <https://docs.deepleaf.io/agronomist-api>; rel="deprecation"; type="text/html"
The Link header is present from day one. v1 is not deprecated.
When v2 lands
v1 responses will additionally carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594). Before the sunset date, v1 behaves exactly as it does today.
We email the address on your account before setting either header. The headers are a backstop, not the announcement.
What counts as a meaning change
- A field that keeps its name but changes unit, range or interpretation.
- A webhook event that fires under different conditions.
- A behaviour the docs promise, such as replacing an untraceable spray hour, that changes.
Meaning changes are listed in this index as API notices.