CF
CertifyForce

CertifyForce API

CertifyForce API Versioning and Deprecation Policy

How the CertifyForce public API is versioned, what counts as a breaking change, and how deprecations are announced with Deprecation and Sunset headers at least 6 months ahead.

Versioning

  • The major version is in the path: /api/v1. The current version is v1 (OpenAPI info.version 1.0.0).
  • Within a major version, changes are additive only: new endpoints, new optional query parameters, new response fields and new enum values. Clients should ignore fields they don't recognise.
  • Breaking changes (removing or renaming a field or endpoint, changing a type, making a parameter required) only ship as a new major version, such as /api/v2.

Deprecation timeline

  1. The new version is released and documented; the old version keeps working unchanged.
  2. From that day, every response from the deprecated version carries a Deprecation header (RFC 9745) with the deprecation date, a Sunset header (RFC 8594) with the shutdown date, and a Link to the migration notes.
  3. The shutdown date is at least 6 months after the deprecation date.
  4. After the sunset date, the old version returns 410 Gone with a JSON error that points at the replacement.

Current status

The unversioned paths under /api/certifications are a deprecated alias of v1, deprecated on 2026-10-15. They return the same data with a Deprecation header and a Link to the v1 URL (rel="successor-version"). No sunset date is scheduled; one will be announced at least 6 months ahead with a Sunset header. Use the /api/v1 paths.

v1 is current and nothing in it is deprecated. Every v1 response already includes Link: <…/docs/deprecation-policy>; rel="deprecation" so clients can find this page.

Changelog

  • 2026-10-15: unversioned /api/certifications paths become a deprecated alias of v1.
  • 2026-10-15: v1 adds RateLimit and RateLimit-Policy headers and the 429 rate_limited error.
  • 2026-10-15: v1 released.

Questions: warren@walters954.com.