backend-api-versioning

Backend API Versioning

Purpose

Manage API version transitions without breaking existing clients. Support coexistence of multiple API versions and provide clear deprecation signals.

Agent Protocol

Trigger

Exact user phrases: "API versioning", "version strategy", "URI versioning", "header versioning", "content negotiation", "accept header", "breaking change", "API migration", "deprecate endpoint", "sunset endpoint", "version path".

Input Context

• Current API version and clients.
• Type of breaking change being introduced.
• Number of active consumers and their upgrade cadence.

Output Artifact

Versioning strategy recommendation or configuration. No file unless requested.

Response Format

Strategy: {URI|Header|Content-negotiation}
Current Version: {v1|v2}
Deprecation Policy: {N versions back|N months}

Completion Criteria

• Versioning strategy chosen and documented
• Current version endpoints are stable
• Deprecation headers present on old versions
• Sunset date communicated via header or docs
• Migration path documented for consumers

Architecture Decision Trees

Versioning Strategy Decision Tree

Do clients control the URL they call?
├── Yes → URI Path Versioning (most common)
├── No → Is content negotiation important?
│   ├── Yes → Content Negotiation (Accept header / media types)
│   └── No → Header Versioning (X-API-Version)

Is the API public or internal?
├── Public → URI path (most explicit for external devs)
│   └── Mobile clients? → URI path (app store can't change headers)
└── Internal → Header versioning (cleaner, version managed by gateway)

How many concurrent versions to support?
├── 2 → URI or Header works well
├── 3+ → URI versioning recommended (explicit routing)
└── 1 (always latest) → Not versioning — additive changes only

Is rapid iteration expected?
├── Yes → No versioning, feature flags, additive changes only
└── No → Formal versioning with deprecation policy (18-month min)