skills.rest
lgzarturo
lgzarturoCOMMUNITY
Explore all skills by this author →
Website𝕏@algforgeGitHub

API Versioning

Design REST API versioning strategies and deprecation workflows.

Updated May 7, 2026
Search Tags:#openapi#deprecation#contract-testing#breaking-changes#rest-api#api-versioning#version-management
One-click install
npx skills add https://github.com/lgzarturo/codeconductor --skill api-versioning-lgzarturo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: API Versioning
Source: https://github.com/lgzarturo/codeconductor/tree/main/.agents/skills/api-versioning
Command: npx skills add https://github.com/lgzarturo/codeconductor --skill api-versioning-lgzarturo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The API Versioning Skill helps teams design and maintain versioned REST APIs with safe deprecation, enabling smooth migrations and predictable client behavior.

Core Features & Use Cases

  • Guidelines for when to version and how to choose between URL path, header, and query parameter versioning.
  • Deprecation workflows with headers, sunset dates, and changelog guidance.
  • OpenAPI strategy for versioned specs and contract testing with Pact.
  • Use Case: When releasing a breaking change, create a new version and provide a migration path for consumers.

Quick Start

Define versioned endpoints (e.g., /api/v1, /api/v2) and implement a deprecation plan that sunsets old versions within a defined timeline.

Frequently Asked Questions about API Versioning

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

FAQPage Schema
What's the best way to version a REST API when releasing breaking changes?▼

REST API versioning for breaking changes involves creating a new version and providing a migration path. You choose between URL path, header, or query parameter versioning, then implement deprecation headers and sunset dates for the old version.

How do I implement an API deprecation workflow with sunset dates and changelogs?▼

API deprecation workflows use deprecation headers, sunset dates, and changelog guidance to sunset old versions within a defined timeline. This ensures smooth migrations and predictable client behavior when consumers transition between API versions.

When should I choose URL path versioning over header versioning for my REST API?▼

URL path versioning defines explicit endpoints like /api/v1 and /api/v2, while header versioning keeps URLs clean. The API versioning decision depends on your framework, client needs, and whether you require visible, cacheable version transitions.

Does this API versioning approach work with OpenAPI specs and Pact contract testing?▼

Yes, the strategy defines OpenAPI evolution for versioned specs and integrates contract testing with Pact. This validates per-version DTO mappings and ensures consumer contracts remain enforced across multiple API versions during migrations.

Can I use this REST API versioning strategy with frameworks like Spring Boot, Express, or FastAPI?▼

Yes, the versioning strategy applies to API teams building multi-version REST APIs across languages and frameworks, including Spring Boot, Express, and FastAPI, handling deprecation timing and breaking changes consistently.

Why do I need per-version DTO mappings when evolving an API with breaking changes?▼

Per-version DTO mappings isolate breaking changes to a specific API version. They allow simultaneous support of multiple API versions, ensuring data transformation rules remain stable while the underlying OpenAPI specification evolves.

Related Skills

Explore More Software Engineering Skills→
khoabdkhoabd

api-interface-design

Design REST APIs with standard HTTP methods, response structures, and OpenAPI specifications.

Community
Intermediate
proffesor-for-testingproffesor-for-testing
436

contract-testing

Verify microservice API providers against consumer-driven Pact contracts in CI/CD pipelines.

Community
Advanced
zinohomezinohome
1

contract-testing-builder

Implements API contract testing using Pact or OpenAPI specifications.

Community
Advanced
CleanExpoCleanExpo
1

API Versioning

Codify URL and header-based API versioning with deprecation policies.

Community
Intermediate