# API Versioning Strategy

> Design versioning for custom Apex REST endpoints: URI versioning, backward compatibility, deprecation sunset. NOT for consuming external APIs — use apex/apex-rest-services.

- Skill: `pranavnagrecha/api-versioning-strategy` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add pranavnagrecha/api-versioning-strategy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pranavnagrecha/api-versioning-strategy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: PranavNagrecha (https://skillmd.com/u/pranavnagrecha)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/pranavnagrecha/api-versioning-strategy

---


# API Versioning Strategy

Custom Apex REST endpoints should be versioned from day one. Two accepted patterns: URI versioning (`/services/apexrest/v1/orders`) or header versioning (`Accept: application/vnd.myco.v1+json`). URI is simpler and more debuggable. This skill defines the class structure, the deprecation sunset policy, and the monitoring required to deprecate safely.

## Adoption Signals

Before publishing a new endpoint or when breaking changes are needed on an existing one. Not for internal-only endpoints with known single consumer.

## Recommended Workflow

1. Always include a version prefix in @RestResource urlMapping, even on v1.
2. Breaking change → new version class; reuse the service layer; deprecate old via response header `Sunset: <date>`.
3. Instrument v1 request counts via Event Monitoring or a custom Log__c record to measure traffic.
4. Notify consumers 90 days before sunset; provide migration doc.
5. Remove v1 only after 0 traffic for 30 days.

## Key Considerations

- Adding a new optional field is NOT a breaking change — do not version for it.
- Renaming a field IS breaking — version.
- Error response shape changes are breaking.
- External consumers cache; give 30+ day sunset windows.

## Worked Examples (see `references/examples.md`)

- *v1 → v2 orders endpoint* — Rename `customerId` to `accountId`
- *Sunset instrumentation* — Before deleting v1

## Common Gotchas (see `references/gotchas.md`)

- **No version on v1** — First breaking change forces coordinated migration.
- **Logic in controller** — Cannot reuse across versions.
- **Silent deletion** — Consumer breaks without warning.

## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)

- No version on initial endpoint
- Breaking v1 without a v2
- Logic inline in controller

## Official Sources Used

- Apex REST & Callouts — https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts.htm
- Named Credentials — https://help.salesforce.com/s/articleView?id=sf.named_credentials_about.htm
- Connect REST API — https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/
- Private Connect — https://help.salesforce.com/s/articleView?id=sf.private_connect_overview.htm
- Bulk API 2.0 — https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/
- Pub/Sub API — https://developer.salesforce.com/docs/platform/pub-sub-api/guide/intro.html