← Docs
Recipe

API versioning policy writer

Generate a clear, enforceable API versioning policy that keeps your consumers sane and your team shipping.

Inputs

  • API surface area — REST, GraphQL, gRPC, or hybrid
  • Release cadence — weekly, biweekly, monthly
  • Deprecation window — how long old versions live
  • Breaking change definition — field removal, type change, semantic shift

Output

A markdown policy document covering versioning scheme (semver vs date-based), URL path strategy, header-based negotiation, deprecation timelines, sunset communication templates, and a changelog format. Includes an enforcement checklist for CI.

Example

## Versioning Scheme
Semantic versioning (MAJOR.MINOR.PATCH).
MAJOR bump = breaking change.

## URL Strategy
/v1/resource — path-based versioning.
No query param or header fallback.

## Deprecation
- Announce via changelog + email 90 days prior.
- Sunset header added 30 days prior.
- Endpoint removed after 90 days.
← Back to docs