Don't Break Your API: Versioning and Deprecation SOP for Vibe Projects

The most common way I've seen a vibe project's API die goes like this: at 3 AM you tell your AI assistant to "rename user_name to camelCase in the response, quick job." It changes it, deploys it, tests pass — and the next morning someone who integrates with your API messages the group: "Everything's broken on my end, I changed nothing." That's when you remember: you announced that field in the docs three months ago. Vibe coding iterates ten times faster than API contracts can move, and that's exactly where it blows up: you can rewrite a prompt freely, but the moment someone calls your API, it becomes a promise.

This guide covers versioning and deprecation specifically, and it deliberately doesn't overlap with the three existing guides — each owns one segment: the prompt version control guide handles versioning of prompt text, which has nothing to do with API contracts; the canary release guide is about rolling out deployments without blowing up production, not about contract lifecycles; the changelog guide is about release communication, not about executing deprecations. This piece fills in the missing puzzle: how contracts change, and how old versions die.

1. The 3 Ways a Vibe Project's API Dies

First, the cost — so you actually have the motivation to run the SOP later. I've seen all three of these happen to real people:

Death #1: Silently changing a field, burning your integrators

The classic. An indie developer built an AI categorization endpoint for his bookkeeping SaaS; v1 returned {"category": "food"}. Six months later he asked Cursor to "clean up the response shape," and it became {"category": {"id": "food", "confidence": 0.97}}. He adapted his own frontend, everything looked fine. But he forgot: three months earlier, a friend building a productivity tool had integrated that endpoint for automatic bookkeeping, reading the string straight off data.category. The next day that friend's users found their books corrupted — [object Object] written into hundreds of ledger entries. Cost of repair: two days of data cleanup on the friend's side, and the friendship nearly didn't survive.

The lesson in one line: any field someone else calls is no longer "your field" — it's a public contract. The most dangerous thing in vibe iteration is that the AI assistant can't see the contract boundary — it sees your repo, not everyone else's.

Death #2: Parallel versions spiraling out of control

The second trap is overcorrection. Someone gets burned once and decides "every change gets a new version from now on" — and suddenly there are /v1, /v2, /v2.1, /v3… each a copy of the handlers with two lines changed. A year later he can't tell which version got which bug fix: a v2 user reports a security hole, he patches it on v3, and v2 users stay exposed. Worse, the docs: four versions of documentation copied from each other, sample code whose version numbers don't match reality, new users following the docs and hitting a half-dead version.

More versions is not more safety. Version count is liability, not asset. On a one-person project, the number of live versions should never exceed 2.

Death #3: Deprecating without notice, getting roasted on HN

The third death hurts the most for reputation. A small, beloved image-background-removal API shut down v1 one day with zero notice — the founder figured "only a few dozen people use v1 anyway." One of those users happened to be the author of a Show HN project; his demo broke completely on the day it hit the HN front page, and he went straight to the comments: "The API author killed the endpoint without a word — steer clear, everyone." That comment got more upvotes than the original post. The service's reputation was essentially frozen in that comment.

Remember: the PR cost of killing an old version without notice always exceeds the engineering cost of maintaining it. A 30-day deprecation notice plus one migration email buys you trust worth far more than three extra months of maintaining the old version.

2. Version Strategy Decision Table: Picking Your Route

The industry really only has three approaches. Here's my five-dimension comparison, calibrated to the reality of solo maintenance:

Dimension	URL path versioning (/v1/users)	Header versioning (Accept: application/vnd.x.v1+json)	No versioning (additive-only)
Solo maintenance cost	Medium: one more set of routes, but the logic stays clear	High: gateway/middleware must parse headers; the version is invisible when debugging	Low: no multi-version maintenance
Client upgrade friction	Low: the URL changed, callers see immediately that they must change	High: forget the header and you silently land on the default version — bugs are hard to trace	None: clients change nothing
Gateway/proxy complexity	Low: Nginx routes by path, one line of config	Medium: route by header, and CDN cache keys must include the version	None
Long-term tech debt	Medium: versions can bloat, but it's controllable (with a deprecation SOP)	Medium-high: version logic hides in middleware; a new maintainer spends three days confused	High: fields only accumulate — in three years the response body is an archaeological site
Debuggability	High: the version is visible in logs, errors, and curl	Low: you only see the header in a packet capture	High: no version problems to debug

My default recommendation, by project stage:

• 0-to-1 solo project, fewer than ~100 public API users: go versionless + additive-only. Your contract is still taking shape at this stage; versioning machinery is over-engineering. Hold one iron rule: only add fields, never change old ones (see the checklist in section 3).
• You have external integrators and you're charging money: switch to URL path versioning (/v1). It's the cheapest to debug and the friendliest to integrators — and it's the mainstream choice of Stripe, GitHub, and Twilio. Header versioning is for big companies with dedicated API teams; one person should not touch it.
• Never: put the version in a query parameter (?version=2). Caches, logs, and gateways all treat it as "the same URL with different params" — spooky bugs are guaranteed eventually.

One-line summary: small projects go versionless on discipline, mid-size projects go /v1 on process, big companies do header versioning on team size — you're one person, pick from the first two.

3. Breaking-Change Checklist: 12 Rules to Print and Pin on the Wall

With the strategy set, 90% of day-to-day agonizing comes down to one question: "Is this change breaking?" Your AI assistant won't judge for you — it only cares that the code runs. These 12 rules are the field-tested standard for REST APIs. Left column is breaking (requires a new version or the deprecation process); right column is safe to ship directly:

✅ Breaking (touches the contract)	❌ Not breaking (ship it)
Renaming a field (user_name → userName)	Adding an optional field (old clients ignore it)
Removing a field (even one marked "deprecated" in docs)	Adding an optional request parameter (with a default)
Changing a field's type (string → number, object → array)	Adding an enum value (clients should handle unknown values gracefully)
Making an optional field required	Making a required field optional (loosening a constraint)
Changing a pagination default (page_size default 20 → 50)	Adding a new standalone endpoint
Changing error codes or error shape (the meaning of code: 1001 changes)	Adding a new error code (old codes keep their meaning)

A few commonly misjudged ones, called out individually:

• Why isn't "adding an enum value" breaking? Because the contract says "you may receive these values" — adding one breaks no existing promise. But only if your docs state "clients must handle unknown enum values gracefully." Without that sentence, adding a value is breaking in practice. That one sentence in your docs costs nothing and pays enormously.
• Why is "changing a pagination default" breaking? Because caller code is full of implicit assumptions like "no page_size passed means 20 items." You change it to 50 and their list layouts break, their "load more" logic breaks. Defaults are part of the contract, not implementation details.
• The sneakiest breaking change: changing error message text. Someone regex-matches your "message": "user not found" for branching; you change it to "User Not Found" and they break. So the error code is the contract — message text should never be depended on. State explicitly in your docs: "message is for humans only and may change at any time."
• Time format and timezone changes are breaking too. 2026-10-11T14:00:00+08:00 → Unix timestamp blows up the other side's parser. Any serialization format change is breaking, full stop.

The companion move for AI assistants: save this table as API_CONTRACT_RULES.md in your project and make the AI read it before every interface change. In vibe coding, the AI is the most frequent "contract breaker" — not because it's malicious, but because it can't see the contract. Feed it the rules and it follows them better than humans do.

4. The 4-Step Deprecation SOP: Letting Old Versions Die With Dignity

A change judged breaking can't just ship — it must go through deprecation. The standard SOP has four steps, each with a concrete deliverable:

Step 1: Tag it — Deprecation + Sunset response headers

The first act of deprecation isn't an announcement — it's making every response from the old version announce "I'm dying" by itself. Use the standard Deprecation and Sunset response headers (RFC 8594 / RFC 9745). This is machine-readable deprecation notice that callers' monitoring can catch directly:

// Express middleware: stamp deprecation on all v1 responses (copy-ready)
const SUNSET_DATE = '2026-12-31T23:59:59Z'; // sunset date, ISO 8601
function deprecationHeaders(req, res, next) {
res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', SUNSET_DATE);
// Link the migration doc so callers know where to look
res.setHeader('Link', '<https://vibefix.work/en/explore/api-v2-migration>; rel="deprecation"');
next();
}
app.use('/v1', deprecationHeaders); // only on old-version routes; v2 untouched

// Advanced: start appending an in-body warning 30 days before sunset
// (one last chance for callers who never read response headers)
function sunsetWarning(req, res, next) {
const daysLeft = Math.ceil((new Date(SUNSET_DATE) - Date.now()) / 86400000);
if (daysLeft <= 30 && daysLeft > 0) {
res.setHeader('Warning', `299 - "v1 API sunsets in ${daysLeft} days, migrate to v2"`);
}
next();
}

Why do headers matter more than announcements? Because announcements rely on humans reading them; headers rely on machines. Any serious integration team monitors upstream API response headers — the moment your Sunset header appears, their alerting fires first. That beats ten emails you could send.

Step 2: Announce it — deprecation notice template (bilingual, copy-ready)

Headers are for machines; announcements are for humans. Send to both channels: email (to known integrators) + changelog (to future integrators). Replace the bracketed parts:

[English]
Subject: [Action Required] {Product} API v1 sunsets on {sunset date} — migrate to v2

Hi,
{Product} API v1 will be sunset on {sunset date}. All v1 responses now
carry a Deprecation header.

What you need to do (about {X} minutes):
1. Read the migration guide: {migration doc link}
2. Key changes: {1-3 breaking changes in one line each}
3. Switch your calls to /v2 before {recommended date}

After sunset, v1 returns 410 Gone permanently. Reply to this email with
questions, or request an extension before {deadline} (evaluated case by case).


主题：[重要] {产品名} API v1 将于 {下线日期} 下线，请迁移至 v2

你好，
{产品名} API v1 将于 {下线日期} 正式下线（Sunset）。v1 目前返回的所有响应
已携带 Deprecation 响应头。

你需要做的事（预计 {X} 分钟）：
1. 阅读迁移指南：{迁移文档链接}
2. 主要变更：{一句话讲清最大的 1-3 个 breaking 变更}
3. 在 {建议完成日期} 前将调用切换到 /v2

下线后 v1 将返回 410 Gone，不再恢复。如有问题回复本邮件，
或在 {截止日期} 前申请延期（我们会个案评估）。

Three details separate a professional announcement from an amateur one: give an estimated time — "about 15 minutes" drives far more action than "please migrate soon"; offer an extension path — if a big customer is genuinely stuck, a case-by-case option creates 90% less friction than a hard cutoff; return 410 Gone after sunset, not 404 — 410 means "this resource existed and is permanently gone," so callers' monitoring can distinguish "it was sunset" from "something broke," which points debugging in completely different directions.

Step 3: Dual-run observation — the old-version traffic decay dashboard

After the announcement, v1 and v2 run side by side. Don't watch for "is anyone complaining" — watch three numbers:

• v1 traffic decay curve: plot daily v1 request counts. Healthy decay is 20–30% per week. If decay stalls at zero for two straight weeks, your announcement didn't reach people — check email open rates, or go @ people directly in their tech channels.
• v1's distinct caller count: more important than total traffic. Going from 50 callers to 3 means those last 3 are the holdouts you follow up with one-on-one. Two weeks out, email those 3 individually and offer pair migration sessions — ten times cheaper than firefighting on sunset day.
• v2's error rate: if migrated callers are erroring heavily on v2, your migration guide is unclear or v2 has bugs. A v2 error spike coinciding with stalled v1 decay is the signal to rewrite the migration guide.

The dashboard doesn't need to be fancy — Grafana, Cloudflare Analytics, or even a daily SQL query pasted into Notion all work. The point is glance at it daily, for 30 days straight. Solo version governance isn't won with tools; it's won with the discipline of "did I look today."

Step 4: Sunset execution checklist

When the Sunset date arrives, work through this list and check each item off:

[] 1. Confirm v1 traffic is below threshold (suggested: under 5% of peak, or <100/day absolute)
[] 2. Send remaining callers a final "48 hours to sunset" email (with migration guide link)
[] 3. Switch v1 routes to return 410 Gone + JSON explanation (with migration link — don't just delete routes)
[] 4. Keep the v1 410 stub for at least 90 days (don't rush to delete code — callers need that signal to debug)
[] 5. Update public docs: banner "sunset" on top of the v1 docs page, linking to the migration guide
[] 6. Publish a changelog entry: "v1 was sunset on {date} — thank you to everyone who migrated"
[] 7. Delete the v1 code after 90 days, tagging v1-final in git for the record

Item 3 deserves elaboration: sunsetting ≠ deleting code. The correct move is replacing the v1 handler with a 10-line 410 stub returning {"error": "v1_sunset", "migration_guide": "{link}"}. A caller getting 410 + a migration link knows what happened in 5 minutes; delete the route and return 404 or 500, and they'll spend half a day tracing it back to "you sunset it." Those 10 lines are the last dignity you can offer your integrators.

5. The One-Page Migration Guide Template for Your Integrators

The migration guide referenced in your announcement shouldn't be an epic. Integrators want one page: which places to change, how to change each, how to verify. Copy this template and fill in the brackets:

# {Product} API v1 → v2 Migration Guide (about {X} minutes)

> v1 sunsets on {sunset date} (returns 410 Gone). v2 went live on {launch date};
> dual-run period is {N} days. Validate in staging first, then cut over production.

## Change overview ({N} breaking changes total)

| # | v1 | v2 | Impact |
|---|----|----|--------|
| 1 | `GET /v1/users` | `GET /v2/users` | Path change — global find/replace |
| 2 | Returns `user_name` (snake_case) | Returns `userName` (camelCase) | Field read sites must change too |
| 3 | Pagination default `page_size=20` | Default `page_size=50`, max 100 | List pages relying on the default must pass it explicitly |

## Step by step

1. **Global-replace the base URL**: `https://api.example.com/v1` → `https://api.example.com/v2`
2. **Batch-rename fields**: update read sites per the mapping below (sed/IDE replace regex included)
`user_name` → `userName`; `created_at` → `createdAt`
3. **Pass pagination explicitly**: every call that omits `page_size` now passes `page_size=20`
(keeps v1 behavior, avoids breakage from the changed default)

## Verification checklist

- [] Smoke tests pass in staging ({list 3-5 core endpoints})
- [] Diff v1 vs v2 responses for the same request (all fields present, types correct)
- [] Check error handling: v2 error code table at {link}; confirm branching uses code, not message
- [] Canary 10% of traffic to v2, watch 24h with no anomalies, then full cutover

## Rollback

v1 stays available until {sunset date}. If v2 hits a blocking issue,
switch back to v1 and contact us at {contact}. v1 will not be restored
after sunset — complete migration before the deadline.

## FAQ

**Q: Does v2 accept v1 field names?**
A: No — v2 is camelCase throughout. Use the batch replace above and do it once.

**Q: Will v1 be throttled or degraded during migration?**
A: No. v1 keeps its original SLA through the dual-run period;
we'll remind you once more 7 days before sunset.

The gold standard for a migration guide: the integrator follows it without thinking. Every change gets a before → after pair; every step gets a verification method. The cardinal sin is listing "v2's shiny new features" without saying "here's how to change your v1 code" — they want surgery steps, not a product launch event.

6. Solo Version Governance: CHANGELOG-Driven + CI That Auto-Blocks Breaking Changes

Everything above is "what to do when it happens." This section is about "making it harder to happen." For a solo-maintained API, the governance system must be light enough that not doing it feels wrong. Two pieces:

1. CHANGELOG-driven: write the changelog before touching the contract

The rule is simple: in any PR that changes the API contract, the changelog entry comes first. Not backfilled at release time — written before the code. Fixed three-part format:

## [Unreleased]
### ⚠️ Breaking
- `GET /v1/users`: `user_name` renamed to `userName` (takes effect in v2; v1 unchanged)
Migration: batch-replace read sites; see {migration guide link}

### Added
- `GET /v2/users` gains optional field `avatar_url`; old clients can ignore it

### Deprecated
- `GET /v1/users` marked deprecated, Sunset {sunset date}, Deprecation header already live

Why does writing the changelog first work? Because writing it forces you to describe the change from the caller's perspective — the moment you type "renamed to userName," you realize "oh, that's breaking." Most silent breakages slip through in the "it's just one line of code" mindset; the changelog is the mechanism that forces you to look up at the contract. The difference from the changelog communication guide: that one is about talking to users at release time; this is about using the changelog as an in-development contract brake pad — one faces outward, one faces inward.

2. CI auto-detection: let openapi-diff block breaking changes

Discipline alone isn't enough — your AI assistant doesn't write changelogs before editing code. Block it in CI: whenever a PR changes the OpenAPI spec, diff it; breaking changes get flagged red and require explicit acknowledgment. Minimal setup (GitHub Actions + oasdiff, one file, no backend):

#.github/workflows/api-contract.yml
name: API Contract Check
on:
pull_request:
paths:
- 'openapi.yaml' # only runs when the spec changed — saves CI minutes

jobs:
diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # need full history to fetch the base branch's spec
- name: Get base spec
run: git show origin/${{ github.base_ref}}:openapi.yaml > /tmp/base.yaml
- name: Install oasdiff
run: go install github.com/oasdiff/oasdiff@latest
- name: Diff specs
id: diff
run: |
oasdiff diff /tmp/base.yaml openapi.yaml \
--format json > /tmp/diff.json
# only care about breaking level: --fail-on turns CI red
oasdiff diff /tmp/base.yaml openapi.yaml \
--fail-on ERR > /tmp/breaking.txt || echo "BREAKING_FOUND=true" >> $GITHUB_ENV
- name: Comment on PR
if: env.BREAKING_FOUND == 'true'
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '⚠️ **Breaking change** detected:\n\n```\n' +
require('fs').readFileSync('/tmp/breaking.txt', 'utf8') +
'\n```\nPlease confirm: 1) CHANGELOG updated under ⚠️ Breaking; ' +
'2) if a new version is needed, the section-4 deprecation SOP is in motion.'
});

Three things make this config sing: the paths filter — no spec change, no run, saving hundreds of CI minutes a month; --fail-on ERR only gates on breaking — additive changes like new fields sail through without noise; the automatic PR comment — it pastes the diff plus "go update the CHANGELOG, go run the deprecation SOP" right in the author's face. Most of the time authors don't refuse to follow the rules; they just forget at merge time.

The prerequisite is having an openapi.yaml. Many vibe projects don't — generating one isn't hard: have your AI assistant reverse-generate it from your route code, about half an hour of work. That spec is the foundation of all version governance: it's the diff input, the docs site input, and the client SDK generation input. API versioning without a spec is castles in the air.

One line to close the whole piece: API versioning isn't a technical problem; it's a promise-management problem. Vibe coding lets you ship ten versions a day, but your integrators can only absorb one "the contract changed" per day. Pick /v1 or versionless, pin the 12 breaking rules on the wall, run the 4-step deprecation SOP, let CI auto-block — with those four layers, even a solo-maintained API can carry itself like a big company's: old versions die with clarity, new versions are born clean, and no integrator gets woken at midnight by your "quick fix." That's the watershed where a vibe project stops being a toy and becomes infrastructure.