Shadow Warden AI API Versioning and Deprecation
How a change is announced before it can break a caller
Versioning
The version is in the URL path. The current and only version is v1. The OpenAPI 3.1 document at /openapi.json declares the v1 base URL in its servers block.
POST https://api.shadow-warden-ai.com/v1/filter ← use this POST https://api.shadow-warden-ai.com/filter ← works, deprecated
What counts as a breaking change
Within v1 we do not remove or rename a field, change a type, tighten a validation rule, or remove an endpoint. Adding an optional field, an endpoint or a response header is not breaking, so clients must ignore fields they do not recognise. A breaking change ships as a new version beside v1, never in place.
How deprecation is signalled
A deprecated resource answers with standard headers a client can act on without reading this page. Today they are sent on every unversioned path. Unversioned paths are served until 2027-08-23.
| Deprecation: @1787443200 | RFC 9745 |
| Sunset: Mon, 23 Aug 2027 00:00:00 GMT | RFC 8594 |
| Link: <successor>; rel="successor-version" | RFC 8288 |
| Link: <policy>; rel="deprecation" | RFC 9745 |
Infrastructure and discovery paths (/health, /metrics, /docs, /openapi.json, /.well-known/*) are not versioned and not deprecated.
The timeline we commit to
- Announce — the Deprecation header and successor link appear, and the change is recorded in the changelog.
- Notice period — at least 180 days between the first Deprecation header and the Sunset date for any versioned resource.
- Sunset — after the date the resource may return 410 Gone.
The sunset date may be extended, never shortened. Related: developer portal, rate limits, authentication.