🔀 API Versioning Strategy

API Versioning Strategy: Public B2B SaaS API, 500 customers, first formal versioning

An API versioning strategy is a structured approach to evolving an API without breaking customers, calibrated to audience and change-type. Based on 20+ API architecture engagements, public APIs with 500+ enterprise customers typically need formal versioning once breaking-change frequency exceeds ~1 per year — which matches your trajectory. Your planned change (restructuring + deprecation) is a natural moment to introduce a versioning scheme that supports the next 5 years of evolution.

The Decision Framework

Three versioning strategies, calibrated to your context:

For you: hybrid — URL-based for major versions (v1, v2) + additive-only between versions.

This gives you: clean separation for big changes, low friction for normal additions.

Your Recommended Approach

1. Adopt URL versioning explicitly. All endpoints served from /api/v1/... (current) and /api/v2/... (future). No implicit versioning.

2. Commit to 'additive-only' between major versions. Any new field, endpoint, or capability ships in current major without bump.

3. Breaking changes batch into v2. Rare event — every 2-3 years.

4. Deprecation cycle: 18 months for your enterprise constraints. Per your SLA of 6+ months, 18 is safe buffer.

When To Version vs. Not

Do NOT bump version for:

• Adding new optional fields to responses
• Adding new endpoints
• Adding new optional query parameters
• Adding new response codes (that clients should already handle)
• Bug fixes that don't change contract
• Performance improvements

DO bump version for:

• Removing fields from responses
• Renaming fields
• Changing field types (string → int)
• Restructuring object hierarchies (your planned change)
• Removing endpoints entirely
• Changing authentication model
• Changing pagination semantics

Your planned change (moving fields to nested profile) = breaking. This is exactly why you need v2.

The Deprecation Playbook

For the /legacy-invoices deprecation + v1 sunset cycle:

Month 0 — Announce:

• Publish v2 with new structure.
• Both v1 and v2 live.
• Email all customers with migration guide.
• Status page announcement.
• Add Sunset header to v1 responses.

Month 3 — First reminder:

• Email customers still on v1.
• Update docs to mark v1 deprecated.

Month 6 — Escalation:

• Email accountable + technical contacts separately.
• Add Deprecation: true header to v1 responses.
• Publish migration metrics dashboard (who's migrated, who hasn't).

Month 12 — Warning:

• Email still-on-v1 customers + their CSMs.
• Add 1-second artificial delay to v1 responses (gentle nudge).
• Rate-limit v1 to 80% of original.

Month 15 — Final:

• Email one more time.
• Document cutover date prominently.

Month 18 — Sunset:

• v1 returns 410 Gone with migration guide link.
• For truly-stuck customers: emergency paid support to migrate.

Sunset Header Implementation

Add to every v1 response starting month 0:

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Mon, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.example.com/migration/v1-to-v2>; rel="successor-version"

Follows RFC 8594 standard. Well-known headers; automated tools can detect.

Communication Plan

Channel 1 — Docs.

Dedicated 'v1 → v2 migration guide' page. Endpoint-by-endpoint diff. Code examples in all supported languages.

Channel 2 — Email.

• Month 0: announcement + migration guide link
• Month 3: reminder
• Month 6: status report
• Month 12: warning
• Month 15: final notice
• Month 18: sunset effective

Channel 3 — Response headers.

Sunset + Deprecation headers on every v1 call. Dev tools surface these.

Channel 4 — Status page / changelog.

Running log of API changes. Customers subscribe for updates.

Channel 5 — Direct CSM outreach (for top 20% of customers).

Hand-holding for enterprise contracts. CSM has v1→v2 tracking dashboard.

Dealing with the Long Tail

Your 10% 'never update without force' customers:

• Month 14: CSM reaches out directly. Offer paid migration assistance.
• Month 17: offer engineering office hours for migration questions.
• Month 18: cutover happens. Expect 2-5 customers to need emergency support.
• Option for enterprise: paid extended-support for v1 (6-12 months). Adds revenue. Only offer to top-20% accounts.

Your Specific Change (Handling the /users restructure)

Approach:

1. Ship v2 /users endpoint with the nested structure.

2. Keep v1 /users serving current (flat) structure for 18 months.

3. Both paths share underlying data layer — just different serializers.

4. For /legacy-invoices (removing entirely): no v2 equivalent needed, just deprecation cycle.

Implementation:

# v1 serializer — current behavior
class UserV1Serializer(serializers.ModelSerializer):
    phone = serializers.CharField()
    address = serializers.CharField()
    # ... flat fields

# v2 serializer — new nested structure  
class UserV2Serializer(serializers.ModelSerializer):
    profile = UserProfileSerializer()
    # fields nested into profile

Routing by URL prefix; separate viewsets. Data stays canonical.

Key Takeaways

• URL-based versioning (v1/v2) + additive-only between versions. Most forgiving for your enterprise API.
• 18-month deprecation cycle. Meets your SLA buffer + handles long-tail customers.
• Sunset + Deprecation headers from day 0 of deprecation. Automated tooling detects; customers surface warnings.