How unLocked CRM Versions Its OpenAPI Spec (and Why You Won't Wake Up Broken)

Our deprecation policy in plain English: 12-month notice for breaking changes, additive-only minor versions, X-Api-Version on every response.

The fastest way to lose developer trust is to ship a breaking API change without warning. Here's exactly how unLocked CRM versions its OpenAPI spec so you can integrate with confidence.

The Three-Number Promise

The OpenAPI info.version follows semver. 2.4.7 means major 2, minor 4, patch 7. Patch and minor releases are additive-only — new endpoints, new optional fields, new enum values that fall back gracefully. Major releases are reserved for genuine breaking changes.

The 12-Month Window

When a major version ships, the previous major stays live for at least 12 months. Both versions are addressable via the X-Api-Version request header. Sunset dates are announced in the changelog the day the new major drops.

Deprecation Signals

  • OpenAPI deprecated: true on the path or field — your generated SDK will surface a warning.
  • HTTP Deprecation and Sunset headers per RFC 8594 on every response that hits a deprecated endpoint.
  • Email + dashboard banner for every API key that has called the deprecated path in the last 30 days.

The Changelog

Every spec change lands in /changelog with a category (added / changed / deprecated / removed), a one-line summary, and a link to the relevant migration guide. Subscribe via RSS so your team finds out before your users do.

Tooling for Drift Detection

Run oasdiff in CI against the latest spec to fail your build the moment a breaking change lands in your consuming code. Combined with our 12-month notice, you'll never be caught flat-footed.

Where This Fits In unLocked