Deprecation & Versioning
Deprecation & versioning
Versioning
The API is versioned in the path: https://api.apievangelist.com/v1. The version changes only
for a breaking change. Everything else — new endpoints, new response fields, new optional
query parameters, new tiers — ships into /v1 without a version bump, so clients should ignore
response fields they do not recognise rather than failing on them.
The contract's info.version (currently 1.2.0) tracks the contract, not the path. It moves
on every published change; the path does not.
What counts as breaking
- Removing an endpoint, or a field from a response.
- Renaming a field, or changing its type.
- Making an optional request parameter required.
- Narrowing an enum, or changing the meaning of an existing value.
- Changing the default page size, or the shape of the paging envelope.
Adding a field, adding an endpoint, adding an optional parameter, widening an enum, or improving a description is not breaking.
Deprecation
When something is going away:
- It is marked in the contract. The operation or field carries
deprecated: truein the OpenAPI, which is the machine-readable signal — an agent or generated client can see it without reading this page. - It is announced in the changelog with the date it was deprecated and the date it will be removed.
- Responses carry the
DeprecationandSunsetheaders (RFC 9745 and RFC 8594), plus aLinkheader withrel="deprecation"pointing at this page. - The replacement is named in the deprecation notice. Nothing is deprecated without somewhere to go.
Notice period
| Change | Minimum notice |
|---|---|
Deprecating an endpoint or field in /v1 | 6 months before removal |
| Retiring an entire API version | 12 months, with /v1 and /v2 served in parallel |
| Security-forced removal | As much as is safe — announced immediately, with the reason |
The only change made without notice is one required to close a security or privacy problem, and that is announced the moment it ships rather than before it.
Retired surfaces
The static per-collection JSON feeds (apis.json, posts.json, and siblings, once documented
at /feeds/*) were retired in favour of this API and the MCP server. The paths redirect rather
than 404 so nothing holding an old link breaks. The two remaining machine-readable catalog
indexes are documented at catalog feeds.
Questions about a deprecation: [email protected].