api-versioning-strategy
Design versioning for custom Apex REST endpoints: URI versioning, backward compatibility, deprecation sunset. NOT for consuming external APIs.
Best use case
api-versioning-strategy is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Design versioning for custom Apex REST endpoints: URI versioning, backward compatibility, deprecation sunset. NOT for consuming external APIs.
Teams using api-versioning-strategy should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/api-versioning-strategy/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How api-versioning-strategy Compares
| Feature / Agent | api-versioning-strategy | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Design versioning for custom Apex REST endpoints: URI versioning, backward compatibility, deprecation sunset. NOT for consuming external APIs.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
Related Skills
shield-event-log-retention-strategy
Use when designing Salesforce Shield Event Monitoring retention, SIEM routing, and storage-tier strategy — which event types to keep, for how long, where, and how to answer audit queries across hot/warm/cold tiers. Triggers: 'shield event log retention', 'route event monitoring to splunk', 'how long to keep login history', 'siem salesforce integration', 'event monitoring storage tier'. NOT for enabling Shield (see salesforce-shield-deployment).
oauth-redirect-and-domain-strategy
Design Connected App OAuth callback URLs, My Domain naming, Enhanced Domains cutover, and cross-environment redirect handling. Trigger keywords: oauth redirect uri, connected app callback, my domain, enhanced domains, sandbox url change, oauth login host. Does NOT cover: end-user login flow UX, Experience Cloud branding, or SAML-only SSO configuration.
mfa-enforcement-strategy
Plan and operate Salesforce org-wide multi-factor authentication (MFA) enforcement: verification methods, phased rollout, SSO and API-only considerations, exemptions, and operational readiness. NOT for designing Login Flow post-authentication logic, IP allowlists, or conditional step-up policies—use ip-range-and-login-flow-strategy, network-security-and-trusted-ips, or transaction-security-policies instead.
ip-range-and-login-flow-strategy
Design and implement Salesforce Login Flows (Screen Flows assigned to profiles or Experience Cloud sites) that run post-authentication to enforce conditional MFA, IP-based branching, terms-of-service acceptance, or user data collection. Covers Login Flow creation in Flow Builder, profile/site assignment, IP-aware decision logic, and ConnectedAppPlugin extension points. NOT for static IP allowlisting or profile Login IP Ranges (see network-security-and-trusted-ips), org-wide session policies, or SSO/SAML IdP configuration.
omniscript-versioning
Use when managing OmniScript versions: activating new versions, deactivating prior versions, testing a specific version before activation, rolling back to a previous version, or understanding version identity (Type/Subtype/Language triplet). NOT for OmniStudio deployment or DataPack migration (use omnistudio/omnistudio-deployment-datapacks).
data-cloud-integration-strategy
Use this skill when designing or troubleshooting the data pipeline strategy for connecting source systems to Data Cloud — including ingestion API pattern selection (streaming vs. batch), connector type decisions, DSO-to-DLO-to-DMO pipeline lag, and lakehouse federation patterns. Triggers on: Data Cloud ingestion API setup, streaming vs batch connector decision, Data Cloud connector types, MuleSoft Direct for Data Cloud, data pipeline lag for segmentation. NOT for standard Salesforce integration patterns (use integration-patterns skill), not for querying Data Cloud once data is ingested (use data-cloud-query-api), not for configuring standard admin connectors through the UI only.
flow-versioning-strategy
Manage Flow versions: activation policy, paused interview compatibility, cleanup cadence, and breaking-change detection. Trigger keywords: flow version management, activate flow version, paused interview, flow cleanup, flow breaking change, flow rollback. Does NOT cover: FlowDefinition metadata deploy order (see devops skill), Process Builder retirement, or Flow test coverage (separate skill).
rollback-and-hotfix-strategy
Planning and executing metadata rollbacks and emergency hotfixes in Salesforce orgs. Use when a production deployment causes regression and needs to be reverted, or when an urgent fix must bypass the normal release pipeline. Covers pre-deploy archive bundles, quick deploy for hotfixes, non-rollbackable component handling, and hotfix branch isolation. NOT for routine CI/CD pipeline setup (use continuous-integration-testing). NOT for destructive changes authoring (use destructive-changes-deployment).
package-development-strategy
Use this skill when deciding between Salesforce package development approaches — unmanaged, unlocked, 1GP managed, or 2GP managed — including namespace selection, ISV distribution requirements, upgrade path design, and AppExchange packaging strategy. Trigger keywords: should I use managed or unlocked package, Salesforce package type selection, 2GP vs 1GP managed package, namespace decision Salesforce, ISV AppExchange packaging, unlocked package strategy. NOT for individual package creation steps, scratch org setup, or day-to-day package version build commands.
environment-strategy
Use when designing the full environment topology for a Salesforce program — selecting which org types to provision, how many, and how they map to your branching strategy and release pipeline. Trigger keywords: 'environment strategy', 'org topology', 'scratch org vs sandbox', 'how many environments do I need', 'environment planning', 'DevOps environment design'. NOT for sandbox-type-only decisions (use admin/sandbox-strategy), NOT for scratch org lifecycle or daily usage (use devops/scratch-org-management), NOT for release pipeline mechanics (use devops/release-management).
external-id-strategy
Use this skill when designing, selecting, or troubleshooting external ID fields on Salesforce objects for upsert operations, cross-system record correlation, or idempotent data loads. Trigger keywords: external ID field design, upsert key strategy, cross-system record matching, source system ID mapping, composite key for uniqueness, duplicate insert on upsert, relationship resolution by external ID. NOT for data migration steps (use data-migration-planning), NOT for REST API upsert endpoint wiring (use rest-api-patterns), NOT for general data model field decisions (use data-model-design-patterns).
multi-org-strategy
Use when deciding whether to use multiple Salesforce production orgs, designing a hub-and-spoke integration topology, reviewing an existing multi-org architecture for risk, or troubleshooting cross-org integration failures. Trigger phrases: 'should we have separate Salesforce orgs', 'how do we share data between two orgs', 'we acquired a company that uses Salesforce', 'our EU data must stay in Europe', 'cross-org integration keeps hitting API limits', 'Salesforce-to-Salesforce stopped working', 'how do we do SSO across multiple orgs'. NOT for sandbox strategy (use sandbox-strategy). NOT for individual integration callout implementation (use integration/ skills). NOT for Named Credential configuration in isolation (use integration/named-credentials-and-callouts).