Api Versioning Strategy

---
name: api-versioning-strategy
description: "Write an API versioning strategy document for a service or API platform. Use when asked to define versioning policy, plan API deprecation, classify breaking changes, or document version lifecycle. Produces a complete versioning strategy with breaking-change classification table, deprecation timeline, migration guide template, and client communication template."
---

# API Versioning Strategy

Produce a complete API versioning strategy document that gives a service team durable, consistent rules for evolving their API without breaking consumers. This document covers the versioning scheme selection (with rationale), lifecycle policy from introduction through sunset, a precise breaking-change classification, and all the communication artifacts a team needs when deprecating a version. Engineers should be able to hand this document to a new team member or external consumer and have them understand exactly what to expect.

## Required Inputs

Ask for these if not already provided:
- **API type** — REST, GraphQL, or gRPC (each has different versioning mechanics)
- **Current versioning approach** — URL path (`/v1/`), request header, query parameter, or none; if none, document starts fresh
- **Number of existing versions and active consumer count** — needed to size the lifecycle policy and migration scope
- **Deprecation timeline constraints** — any hard deadlines (contract SLAs, compliance windows, annual release cycles)
- **Consumer type** — internal teams only, external partners, public API, or mix (affects communication channel choices)

If any input is missing, ask before producing the document. For GraphQL, note that the versioning approach differs substantially (schema evolution over versioning) and tailor the scheme section accordingly.

## Output Format

---

# API Versioning Strategy: [Service Name]… load the full skill through Skill Me