skills.rest
CagesThrottleUs
CagesThrottleUsCOMMUNITY
Explore all skills by this author →
GitHub

api-versioning

Generates API versioning strategy ADRs, deprecation policies, and CI breaking-change detection for external APIs.

Updated May 21, 2026
Search Tags:#openapi#adr#deprecation#breaking changes#rest api#api versioning#oasdiff
One-click install
npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill api-versioning-cagesthrottleus
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-versioning
Source: https://github.com/CagesThrottleUs/private-ai-harness/tree/main/skills/api-versioning
Command: npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill api-versioning-cagesthrottleus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Externally-facing APIs break consumers when they evolve without a documented versioning strategy, breaking-change policy, or deprecation timeline. This Skill produces the complete governance artifacts and CI enforcement needed to evolve an API safely. ## Core Features & Use Cases - Versioning Strategy ADR: Selects URL path, header, or content-negotiation versioning with Stripe and Kubernetes evidence, documented as an architecture decision record. - Breaking-Change Policy & Deprecation Timeline: Defines which changes require a new version, plus a 12-month deprecation schedule with RFC 8594 Sunset headers and middleware examples in Python and Go. - CI Breaking-Change Detection: Adds oasdiff to GitHub Actions to automatically block PRs that introduce breaking OpenAPI changes. - Use Case: Before launching a public REST API, run this Skill to produce the ADR, versioning policy, migration guide template, and CI check, then have the api-versioning-reviewer agent validate all artifacts before committing. ## Quick Start Use the api-versioning skill to create a versioning strategy ADR, deprecation policy, and oasdiff CI check for my externally-facing REST API.

Frequently Asked Questions about api-versioning

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose an API versioning strategy for a REST API?▼

URL path versioning (/v1/users) is the recommended default for new REST APIs because it is explicit, easy to document, and simple to route. Header-based versioning suits date-based schemes like Stripe, while content negotiation fits hypermedia APIs.

What API changes are considered breaking changes?▼

Breaking changes include removing response fields, changing field types, making optional fields required, changing error codes, removing endpoints, or changing HTTP methods. Adding optional fields, endpoints, or parameters is non-breaking.

How do I detect breaking OpenAPI changes in CI?▼

Use oasdiff in a GitHub Actions job that diffs the PR's openapi.yaml against the base branch spec. The job fails on breaking changes, blocking the PR until a new API version is created or the change is reverted.

How do I deprecate an old API version with Sunset headers?▼

Follow RFC 8594 by adding Deprecation: true, a Sunset date header, and a Link header with rel="successor-version" to old-version responses. The skill provides middleware examples for Flask/FastAPI and Go, plus a 12-month retirement timeline.

When should I skip formal API versioning?▼

Skip formal versioning for internal-only services with a single consumer, prototype or alpha APIs marked as such, and CLI-only tools with no HTTP interface. The skill prompts for confirmation before skipping.

Related Skills

Explore More Software Engineering Skills→
dhruvinrsonidhruvinrsoni

api-contract-design

Design REST or gRPC API contracts using OpenAPI or Protobuf specifications.

Community
Advanced
kazdenckazdenc
42

deploy-check

Executes a pre-deployment checklist covering code, database migrations, environment variables, dependencies, performance, monitoring, rollback procedures and smoke tests for production releases.

Community
Advanced
jaktestowacjaktestowac
113

testing-api-contracts

Validates API responses against OpenAPI or JSON Schema and classifies spec changes as safe, risky, or breaking.

Community
Advanced
snoodleboot-iosnoodleboot-io

api-versioning-strategy

Guides API versioning decisions using compatibility classification, expand-migrate-contract, and sunset patterns.

Official
Intermediate