CloudYali API Versioning & Deprecation Policy
The CloudYali public API is versioned in the URL path and is currently v1. This page is the contract: what CloudYali may change without telling you, what it may not, and exactly how a retirement is announced.
How the CloudYali API is versioned
The major version is part of the path: https://www.cloudyali.io/api/v1/features. There is no version header to negotiate and no implicit “latest” — the URL you call is the version you get, permanently.
Every response also carries API-Version, so a client can log which version actually served it without parsing URLs.
What CloudYali may change within a version
Within a major version, changes are additive only. Write clients that ignore fields they do not recognise and they will not break.
| Change | Breaking? | Ships in |
|---|---|---|
| A new endpoint | No | Same major version |
| A new optional query parameter | No | Same major version |
| A new field in a response object | No | Same major version |
| A new value in an existing enum | No | Same major version |
| A new error code | No | Same major version |
| Removing or renaming an endpoint | Yes | New major version |
| Removing or renaming a response field | Yes | New major version |
| Making an optional parameter required | Yes | New major version |
| Narrowing an accepted value | Yes | New major version |
| Changing a default | Yes | New major version |
How CloudYali announces a deprecation
A deprecated endpoint keeps working. From the moment it is announced until at least 180 days later, every one of its responses carries the headers below. Nothing is removed without them.
HTTP/1.1 200 OK
API-Version: v1
Deprecation: @1767225600
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://www.cloudyali.io/developers/api-versioning>; rel="deprecation"; type="text/html",
<https://www.cloudyali.io/api/v2/features>; rel="successor-version"Deprecation— RFC 9745. An@-prefixed Unix timestamp for the moment the endpoint was announced as deprecated.Sunset— RFC 8594. The HTTP-date after which the endpoint stops responding.Link; rel="deprecation"— this page. Present on every API response, deprecated or not, so a client can find the policy without knowing it exists.Link; rel="successor-version"— where to move to, when there is a direct replacement.
CloudYali endpoints currently deprecated
None. No endpoint in the CloudYali public API is scheduled for retirement. This list is generated from the same record the API reads when it decides whether to emit a Sunset header, so it cannot drift out of date.
Reading the CloudYali policy programmatically
The same policy is published as an x-lifecycle extension in the OpenAPI document, and summarised in the discovery index — so a client can check it without parsing this page.
curl -s https://www.cloudyali.io/openapi.json | jq '."x-lifecycle"' curl -s https://www.cloudyali.io/api | jq '.data.versioning' curl -sI https://www.cloudyali.io/api/v1/features | grep -i -E 'api-version|deprecation|sunset|link'
Getting notified about CloudYali API changes
Deprecations are announced on the CloudYali changelog and in the response headers above. If you run an integration you would like us to warn directly, email support@cloudyali.io and we will add you to the list.