API versioning and deprecation policy

API versioning

Certorix REST API uses URL path versioning: /api/v1/trees, /api/v2/facts, etc. Current version is v1.

Version lifecycle

• Stable – Current version. All new features added here.
• Deprecated – Old version still works but no new features. Receives security fixes only.
• Sunset – Version no longer available. Requests return 410 Gone.

Deprecation notice period

• Certorix announces deprecation at least 6 months in advance for breaking changes.
• Notifications sent to: email of all admins, in‑app banner, and API response header X-Deprecation-Notice.
• During deprecation period, the API returns a warning header: X-Deprecation-Warning: true.

Breaking vs non‑breaking changes

Non‑breaking (no new version) – Adding new fields to responses, adding new endpoints, relaxing validation rules.

Breaking (new version required) – Removing fields, changing field types, changing validation rules to be stricter, changing URL structure.

Checking your API version usage

The audit log records which API version each request used. Filter by 'api.version' to see if you are still using deprecated versions.

Upgrading to new API version

1. Review the changelog (/api/changelog or email notifications).
2. Update your client code to use the new version URL (/api/v2/...).
3. Test in staging environment.
4. Deploy to production.
5. Monitor audit log for any remaining calls to old version.

Beta API versions

Experimental features may be available at /api/beta/.... Beta endpoints:

• May change or be removed without notice.
• Not recommended for production use.
• No deprecation period.
• Documented in 'Beta API' section of docs.