From 2e393a83d5189e4fa48e5a590804518da81e68ba Mon Sep 17 00:00:00 2001 From: Viljami + Claude Date: Thu, 30 Apr 2026 12:45:13 +0000 Subject: [PATCH] docs: move API versioning to getting started page Move the API versioning and compatibility documentation from docs/architecture/api-first.md to the API landing page at /api. - Add Versioning section with compatibility guarantees, deprecation policy, and breaking change definitions to src/pages/api.tsx - Replace detailed content in api-first.md with a link to /api#versioning - Update TOC to include the new Versioning section https://claude.ai/code/session_01HVZbXfysvdk6kjDbJvU7zj Co-authored-by: Claude --- docs/architecture/api-first.md | 37 +------------------------ src/pages/api.tsx | 49 ++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 36 deletions(-) diff --git a/docs/architecture/api-first.md b/docs/architecture/api-first.md index 16d1167..58d5b22 100644 --- a/docs/architecture/api-first.md +++ b/docs/architecture/api-first.md @@ -31,42 +31,7 @@ Webhooks are the primary mechanism for outbound integrations — ERPs, middlewar ## API Versioning & Compatibility -epilot maintains strong backwards compatibility commitments for all public APIs. This ensures integrations remain stable and predictable over time. - -### Compatibility Guarantees - -- **No breaking changes to existing operations** — existing API endpoints, request/response schemas, and webhook/event payloads remain backwards compatible -- **Additive changes only** — new fields, parameters, and endpoints may be added at any time; consumers should ignore unknown fields -- **Minimum two years support** — any published API route is supported for at least two years from its release - -### Deprecation Policy - -When an API operation needs to be retired: - -1. **12-month notice period** — breaking changes are announced at least 12 months in advance -2. **Deprecation in OpenAPI spec** — deprecated operations are marked in the [OpenAPI definitions](/api), which propagates to generated SDKs and documentation -3. **Changelog announcement** — all deprecations are published in the [API Changelog](/api/changelog), available via RSS feed or email notifications - -:::note Exceptions -Security vulnerabilities or regulatory/legal requirements may necessitate changes on shorter notice. In such cases, as much advance notice as feasible will be communicated. -::: - -### What Constitutes a Breaking Change - -- Removing an API endpoint (sunsetting) -- Removing or renaming a required request parameter -- Removing or renaming a response field -- Changing the type or format of an existing field -- Changing error codes or response status codes for existing scenarios -- Tightening validation on existing parameters - -### Staying Informed - -Subscribe to API changes through: - -- **[API Changelog](/api/changelog)** — detailed changelog with RSS feed support -- **OpenAPI specs** — deprecation notices embedded in API definitions -- **Release notes** — major platform updates announced via email to registered developers +epilot maintains strong backwards compatibility commitments for all public APIs. See the [API Versioning](/api#versioning) section for details on compatibility guarantees, deprecation policies, and what constitutes a breaking change. ## Accessing APIs with MCP diff --git a/src/pages/api.tsx b/src/pages/api.tsx index 0c44831..0a0ce72 100644 --- a/src/pages/api.tsx +++ b/src/pages/api.tsx @@ -19,6 +19,7 @@ const toc = [ { value: 'SDK', id: 'sdk', children: [], level: 2 }, { value: 'Entities', id: 'entities', children: [], level: 2 }, { value: 'Webhooks', id: 'webhooks', children: [], level: 2 }, + { value: 'Versioning', id: 'versioning', children: [], level: 2 }, { value: 'Changelog', id: 'changelog', children: [], level: 2 }, { value: 'API Reference', id: 'api-reference', children: [], level: 2 }, ]; @@ -113,6 +114,54 @@ yarn add @epilot/entity-client`} and signature verification.

+

Versioning

+

+ epilot maintains strong backwards compatibility commitments for all public APIs. +

+

Compatibility Guarantees

+ +

Deprecation Policy

+ +

+ + Exceptions: Security vulnerabilities or regulatory requirements may necessitate changes on shorter + notice. + +

+

Breaking Changes

+

The following are considered breaking changes:

+ +

Changelog

Breaking changes, new endpoints, and updates are published in the{' '}