The version is in the path, fields are only added within a version, and a retired path keeps serving for at least 90 days with headers that say so.
Where the version is
This is version 1 of the presentations API. Every /api/presentations/...
endpoint also answers at /api/v1/presentations/..., for example
/api/v1/presentations/create, serving exactly what the unversioned path
serves. The versioned address is the durable one to integrate against; the
unversioned /api/... form stays as an alias. The live creation endpoints and
the agent tool API are versioned at the root, /v1/....
What changes within a version
Within a version, fields are only added, never removed or retyped. These changes are compatible and can arrive without notice:
- new optional request fields
- new response fields
- new endpoints
- new enum values on fields documented as open
How a breaking change ships
A breaking change ships under a new path prefix, /api/v2/..., while v1
keeps serving. A retired prefix keeps serving for at least 90 days, and during
that time its responses carry three headers:
Deprecation(RFC 9745): the date the old path was deprecated.Sunset(RFC 8594): the date the old path stops serving, at least 90 days out.Linkwithrel="successor-version": the new path.
The same policy for machines
The OpenAPI document states this policy in
info.x-versioning and, field by field, in info.x-lifecycle.
x-lifecycle.deprecated lists every path currently in its notice period; it
is empty today.
Back to the API overview.