api-versioning-strategy

SKILL.md

API Versioning Strategy

Table of Contents

Overview

When to Use

Quick Start

Reference Guides

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:

// 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
Versioning Approaches

Backward Compatibility Patterns
Backward Compatibility Patterns

Deprecation Strategy
Deprecation Strategy

Migration Guide Example
Migration Guide Example

Response Structure
Response Structure

Date Format
Date Format, Error Format

JavaScript/TypeScript
JavaScript/TypeScript, Python

GraphQL Versioning
GraphQL Versioning

gRPC Versioning
gRPC Versioning

Version Detection & Routing
Version Detection & Routing

Testing Multiple Versions
Testing Multiple Versions

Pattern 1: Version-Agnostic Core
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

1d:[