api-versioning_skill

Overview

This skill guides designing and evolving APIs with explicit versioning and strict rules to avoid breaking clients. It emphasizes starting with versioning from day one, supporting multiple versions concurrently, and using clear deprecation and sunset procedures. Followable patterns and protocols reduce risk and preserve client trust.

How this skill works

The skill inspects API change plans and flags any breaking changes that require a new version. It recommends concrete versioning strategies (URL path, header, query param), outlines migration patterns for evolving data shapes, and prescribes a deprecation protocol including headers, logging, and sunset behavior. It also provides pressure-resistance responses for common stakeholder objections.

When to use it

• Designing new APIs or endpoints
• Modifying endpoints in ways that could affect clients
• Planning an API evolution or migration strategy
• Reviewing PRs for interface or schema changes
• Creating deprecation or sunset plans for older versions

Best practices

• Version from day one (start with /v1/ in the path)
• Never make breaking changes to a released version—create vN+1 instead
• Support old versions by adapting new data models for legacy responses
• Announce deprecation via headers, docs, and logs; provide a minimum migration period (6+ months)
• Log usage of deprecated endpoints to track client migration progress

Example use cases

• Splitting a combined name field into firstName/lastName while still serving v1 clients
• Adding a required field: introduce it in v2 and keep v1 unchanged
• Removing an endpoint: deprecate with sunset headers and maintain behavior during the deprecation window
• Fixing a behavior that changes semantics: implement the fix in a new version and document migration steps
• Accepting a new optional field or adding a non-breaking endpoint extension