amey-thakur/ai-skills/api-versioning
Claude Code and agent skill by amey-thakur/ai-skills
- community
Checking that the SKILL.md file is still in the repository.
Version APIs so existing clients keep working while the contract evolves, with a real sunset process. Use when choosing a versioning scheme or planning a breaking API change.
Install
npx vskill@latest install amey-thakur/ai-skills/api-versioningSKILL.md
The same SKILL.md was published earlier as amey-thakur/ai-skills/api-versioning.
API versioning
The best version strategy is needing versions rarely: evolve additively, and when you must break, break loudly, once, with a long runway.
Method
- Exhaust additive evolution first. New optional fields, new
endpoints, new enum values (documented as open sets) are not breaking. Removing, renaming, retyping, tightening validation, changing defaults or error codes are. Keep the taxonomy written down where reviewers see it (see api-change-management).
- Pick URL-path versioning unless you have a reason.
/v1/orders
is visible in logs, testable in a browser, cacheable, and impossible to send by accident. Header/date-based versioning (Stripe-style pinning) is strictly better ergonomics at much higher implementation cost; choose it deliberately, not aspirationally.
- Version the whole surface, not per endpoint.
/v1/orderswith
/v2/refunds forces every client to carry a compatibility matrix. One version number, moved rarely.
- Keep old versions thin, not forked. Implement vN-1 as a translation
layer over the vN core (request/response adapters), or the old version stops getting bug fixes and becomes a second product.
- Run sunsets as a program. Announce with dates; emit
Deprecation and Sunset headers; instrument per-client version usage; contact the top consumers directly; brown-out (planned short outages) before the final cut. A version you cannot measure usage of is a version you can never remove.
- Give every response a version fingerprint. Echo the resolved
version in a header so support tickets and logs are unambiguous about what contract the client saw.
Boundaries
- Internal APIs with deployable consumers usually need coordinated
releases, not versions; versioning is for clients you do not control.
- Do not use versions as a feature-flag system; flags gate features
inside a contract, versions change the contract.
- Event and webhook payloads version separately from the request API and
are easier to break by accident; apply the same additive-only rule there (see webhooks-design).
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/backend/api-versioning/SKILL.md
Popularity
- Repository stars
- 10
- Repository forks
- 2
- 7-day trend score
- 17
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/amey-thakur/ai-skills/api-versioning)