AI agent skill · by @aj-geddes

Api Versioning Strategy

Implement API versioning strategies including URL versioning, header versioning, backward compatibility, deprecation strategies, and migration guides. Use when dealing with API versions, deprecating endpoints, or managing breaking changes.

Archived 2026-10-23 · Source updated 2026-03-04 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# API Versioning Strategy

## Table of Contents

- [Overview](#overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Reference Guides](#reference-guides)
- [Best Practices](#best-practices)

## Overview

Comprehensive guide to API versioning approaches, deprecation strategies, backward compatibility techniques, and migration planning for REST APIs, GraphQL, and gRPC services.

## When to Use

- Designing new APIs with versioning from the start
- Adding breaking changes to existing APIs
- Deprecating old API versions
- Planning API migrations
- Ensuring backward compatibility
- Managing multiple API versions simultaneously
- Creating API documentation for different versions
- Implementing API version routing

## Quick Start

Minimal working example:

```typescript
// express-router.ts
import express from "express";

const app = express();

// Version 1
app.get("/api/v1/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe" }],
  });
});

// Version 2 - Added email field
app.get("/api/v2/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe", email: "john@example.com" }],
  });
});

// Shared logic with version-specific transformations
app.get("/api/:version/users/:id", async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (req.params.version === "v1") {
    res.json({ id: user.id, name: user.name });
// ... (see reference guides for full implementation)
```

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [Versioning Approaches](references/versioning-approaches.md) | Versioning Approaches |
| [Backward Compatibility Patterns](references/backward-compatibility-patterns.md) | Backward Compatibility Patterns |
| [Deprecation Strategy](references/deprecation-strategy.md) | Deprecation Strategy |
| [Migration Guide Example](references/migration-guide-example.md) | Migration Guide Example |
| [Response Structure](references/response-structure.md) | Response Structure |
| [Date Format](references/date-format.md) | Date Format, Error Format |
| [JavaScript/TypeScript](references/javascripttypescript.md) | JavaScript/TypeScript, Python |
| [GraphQL Versioning](references/graphql-versioning.md) | GraphQL Versioning |
| [gRPC Versioning](references/grpc-versioning.md) | gRPC Versioning |
| [Version Detection & Routing](references/version-detection-routing.md) | Version Detection & Routing |
| [Testing Multiple Versions](references/testing-multiple-versions.md) | Testing Multiple Versions |
| [Pattern 1: Version-Agnostic Core](references/pattern-1-version-agnostic-core.md) | Pattern 1: Version-Agnostic Core, Pattern 2: Feature Flags for Gradual Rollout, Pattern 3: API Version Metrics |

## Best Practices

### ✅ DO

- Version from day one (even if v1)
- Document breaking vs non-breaking changes
- Provide clear migration guides with code examples
- Use semantic versioning principles
- Give 6-12 months deprecation notice
- Monitor usage of deprecated APIs
- Send deprecation warnings to API consumers
- Support at least 2 versions simultaneously
- Use adapters/transformers for version logic
- Test all supported versions
- Log which API version is being used
- Provide migration tooling when possible
- Be consistent with versioning approach

### ❌ DON'T

- Change API behavior without versioning
- Remove versions without notice
- Support too many versions (>3)
- Use different versioning strategies in same API
- Break APIs without incrementing version
- Forget to update documentation
- Deprecate too quickly (<6 months)
- Ignore feedback from API consumers
- Make every change a new version
- Use version numbers inconsistently