skills.rest
CleanExpo
CleanExpoCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

API Versioning

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

1|Updated Sep 14, 2025
Search Tags:#versioning#api#fastapi#rest#next.js#deprecation
One-click install
npx skills add https://github.com/CleanExpo/DR-NRPG --skill api-versioning-cleanexpo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: API Versioning
Source: https://github.com/CleanExpo/DR-NRPG/tree/main/.skills/custom/api-versioning
Command: npx skills add https://github.com/CleanExpo/DR-NRPG --skill api-versioning-cleanexpo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the complexities of managing different versions of an API, ensuring smooth transitions for users and preventing service disruptions during updates.

Core Features & Use Cases

  • URL and Header Versioning: Implements versioning strategies for both URL prefixes (e.g., /api/v1/) and request headers (e.g., Accept-Version).
  • Deprecation Policies: Defines clear timelines and mechanisms for retiring older API versions, including Deprecation and Sunset headers.
  • Backward-Compatible Evolution: Guides on how to evolve APIs without breaking existing clients.
  • Use Case: When releasing a new version of your API that includes breaking changes, this skill helps you implement a strategy to introduce /api/v2/ while gracefully phasing out /api/v1/ with clear deprecation notices.

Quick Start

Implement URL prefix versioning for FastAPI routes by creating separate routers for v1 and v2 and mounting them under /api.

Frequently Asked Questions about API Versioning

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

FAQPage Schema
How do I manage API versioning and deprecation in FastAPI?▼

API versioning in FastAPI is managed by creating separate routers for different versions and mounting them under URL prefixes like `/api/v1/`. This approach groups routes by version, allowing you to introduce new versions and deprecate older ones safely.

What is the best way to deprecate an old REST API version?▼

The best way to deprecate a REST API version is to use `Deprecation` and `Sunset` HTTP headers. This provides clear timelines for clients, allowing you to phase out older versions gracefully while maintaining backward-compatible evolution strategies.

Does this API versioning skill support header-based version negotiation for Next.js?▼

Yes, this skill supports header-based version negotiation for Next.js API routes using headers like `Accept-Version`. It codifies patterns for both URL prefix and header-based versioning to manage version negotiation effectively.

How do I evolve APIs without breaking existing clients?▼

To evolve APIs without breaking existing clients, you must adhere to backward-compatible evolution strategies. This involves deprecating endpoints before removing them, managing version negotiation, and providing clear migration guides for users.

When do I need URL prefix versioning versus header-based versioning?▼

URL prefix versioning uses paths like `/api/v1/` for clear route separation, while header-based versioning uses request headers for negotiation. You need URL prefixes for router-level grouping and headers for transparent version negotiation.

Related Skills

Explore More Software Engineering Skills→
CleanExpoCleanExpo
1

Audit Trail

Implement structured audit trail logging with FastAPI middleware and PostgreSQL storage.

Community
Advanced
FaysilAlshareefFaysilAlshareef
4

versioning

Configure API versioning for .NET projects with URL, header, and query methods.

Community
Intermediate
tranhieutttranhieutt
70

api-design

Review REST and GraphQL API contracts for naming, schema, auth, and versioning issues.

Community
Intermediate
cdalsoniiicdalsoniii

API Versioning

Design API versioning strategies and generate migration documentation for breaking changes.

Community
Intermediate