amey-thakur/ai-skills/api-versioning

Claude Code and agent skill by amey-thakur/ai-skills

Trust tier 3
  • community
Source check pending

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-versioning

SKILL.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

  1. 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).

  1. 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.

  1. Version the whole surface, not per endpoint. /v1/orders with

/v2/refunds forces every client to carry a compatibility matrix. One version number, moved rarely.

  1. 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.

  1. 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.

  1. 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/amey-thakur/ai-skills/api-versioning/badge)](https://verified-skill.com/skills/amey-thakur/ai-skills/api-versioning)

Something wrong with this skill or its page? Tell us.