{"id":"openapi-versioning-and-deprecation","slug":"openapi-versioning-deprecation-policy-insurance-crm","title":"How unLocked CRM Versions Its OpenAPI Spec (and Why You Won't Wake Up Broken)","excerpt":"Our deprecation policy in plain English: 12-month notice for breaking changes, additive-only minor versions, X-Api-Version on every response, and an honest changelog you can RSS-subscribe to.","content":"<p>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.</p>\n\n<h2>The Three-Number Promise</h2>\n<p>The OpenAPI <code>info.version</code> follows semver. <code>2.4.7</code> means major 2, minor 4, patch 7. Patch and minor releases are <strong>additive-only</strong> — new endpoints, new optional fields, new enum values that fall back gracefully. Major releases are reserved for genuine breaking changes.</p>\n\n<h2>The 12-Month Window</h2>\n<p>When a major version ships, the previous major stays live for at least 12 months. Both versions are addressable via the <code>X-Api-Version</code> request header. Sunset dates are announced in the changelog the day the new major drops.</p>\n\n<h2>Deprecation Signals</h2>\n<ul>\n<li><strong>OpenAPI <code>deprecated: true</code></strong> on the path or field — your generated SDK will surface a warning.</li>\n<li><strong>HTTP <code>Deprecation</code> and <code>Sunset</code> headers</strong> per RFC 8594 on every response that hits a deprecated endpoint.</li>\n<li><strong>Email + dashboard banner</strong> for every API key that has called the deprecated path in the last 30 days.</li>\n</ul>\n\n<h2>The Changelog</h2>\n<p>Every spec change lands in <code>/changelog</code> 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.</p>\n\n<h2>Tooling for Drift Detection</h2>\n<p>Run <code>oasdiff</code> in CI against the latest spec to fail your build the moment a breaking change lands in <em>your</em> consuming code. Combined with our 12-month notice, you'll never be caught flat-footed.</p>","category":"Reference","featureLink":"/mcp-server","cluster":"mcp-api","date":"2026-11-18","lastModified":"2026-11-18","readTime":"6 min","author":"unLocked Team"}