api-versioning

Design API versioning strategies with URI paths, headers, and deprecation workflows.

1|1|Updated Jan 3, 2026

Search Tags:#versioning #api #routing #deprecation #elixir #backward-compatibility #gateway

Ready to run

npx skills add https://github.com/layeddie/ai-rules --skill api-versioning-layeddie

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-versioning
Source: https://github.com/layeddie/ai-rules/tree/main/skills/api-versioning
Command: npx skills add https://github.com/layeddie/ai-rules --skill api-versioning-layeddie

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps teams plan, design, and manage API versioning strategies to evolve contracts safely without breaking existing clients.

Core Features & Use Cases

URI path versioning for clear, separate endpoints per version.
Header-based versioning to respect content negotiation and client flexibility.
Deprecation workflows and backward-compatibility patterns for gradual evolution.
Gateway integration guidance for coordinated multi-version deployments.

Quick Start

Configure your gateway to expose v1 and v2 endpoints and implement a deprecation schedule.

Frequently Asked Questions about api-versioning

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

FAQPage Schema

What is the best way to design API versioning for backward compatibility?▼

API versioning strategies include URI path versioning for clear separate endpoints and header-based versioning to respect content negotiation. Both approaches support backward compatibility and allow gradual contract evolution without breaking existing clients.

How do I implement a deprecation timeline for old API versions?▼

To implement a deprecation timeline, configure your gateway to expose both current and deprecated endpoints simultaneously. Establish clear breaking-change workflows and communicate deprecation schedules to clients, allowing gradual migration and backward compatibility across your services.

URI path versioning vs header-based versioning: which approach should I use?▼

URI path versioning provides clear, separate endpoints per version for straightforward routing, while header-based versioning respects content negotiation and offers client flexibility. Your choice depends on whether you prioritize explicit endpoint separation or transparent contract evolution.

Can I coordinate multi-version API deployments through an API gateway?▼

You can coordinate multi-version API deployments through gateway integration. By configuring the gateway to expose multiple endpoints like v1 and v2, you manage routing, enforce backward compatibility, and execute deprecation schedules across distributed services.

When do I need to introduce a new API version instead of a backward-compatible update?▼

You need a new API version when implementing breaking changes that cannot be resolved through backward-compatible patterns. Introduce a new version alongside the old one, then use deprecation workflows and timelines to gradually migrate clients safely.

Does API versioning work with Elixir services requiring multi-version support?▼

API versioning works with Elixir services by applying URI path or header-based versioning strategies. It supports multi-version endpoints, backward compatibility patterns, and gateway integration to coordinate deployments and manage contract evolution safely.