API Versioning and Evolution Strategy

Wrote docs/architecture/tasks/orders-api-v2-001/api-versioning-design/api-versioning-spec.md. Complete API versioning and evolution specification establishing URI path routing, RFC 8594 sunset protocols, a 12-month migration runway, and dual-run translation adapters.

---
skill: api-versioning-design
---

# API Versioning and Evolution Specification: Core Order Fulfillment API [VER-ORD-001]

## Summary

This specification establishes the API versioning and lifecycle evolution architecture for `orders-api` under run ID `orders-api-v2-001`, governing the breaking migration from `v1.4` to `v2.0` across 1,400 external merchant integrations. It resolves the conflict between backend purity and external partner ergonomics by rejecting content negotiation headers (`Accept` header versioning) in favor of explicit, cache-friendly URI path versioning (`/v1/orders` alongside `/v2/orders`). To prevent the merchant integration failures demonstrated in incident INC-1980, the design mandates a 12-month migration runway, dual-run translation adapters deployed at the ingress gateway, automated RFC 8594 `Deprecation` and `Sunset` response headers, and additive-only non-breaking schema evolution within minor releases.

## Detailed Description

External B2B APIs serve third-party software stacks beyond the provider's operational control. Forcing breaking schema updates or obscure header requirements breaks client applications, accumulates customer churn, and overburdens partner engineering support.

Incoming Merchant Request
│
├─► POST /v1/orders ──► [ v1 Ingress Route ]
│ │
│ ▼
│ [ RFC 8594 Header Injector ]
│ ├── Deprecation: @1789456200
│ └── Sunset: Wed, 16 Sep 2027 00:00:00 GMT
│ │
│ ▼
│ [ Bi-Directional Translation Adapter ]
│ │ (Maps legacy fields to v2 schema)
│ ▼
└─► POST /v2/orders ──► [ Canonical Core Order Service v2.0 ]

### Criteria and weights

| Criterion | Why it matters here | Weight | Source of the weight |
|---|---|---|---|
| Merchant Integration Compatibility | Third-party ERPs and webhooks cannot adjust to subtle header changes quickly (INC-1980). | 0.40 | Alex Mercer (Merchant VP) |
| Non-Breaking Evolution Freedom | Internal teams must deliver backward-compatible enhancements without release blockages. | 0.25 | Sarah Chen (API Standards) |
| Deprecation Observability & Automation | Partner developers must receive programmatic sunset signals directly in HTTP responses. | 0.20 | RFC 8594 Standards Mandate |
| Gateway Routing & Caching Simplicity | Intermediate CDNs, reverse proxies, and edge caches must partition versions cleanly. | 0.15 | Infrastructure Operations |


### Comparison

| Strategy Candidate | Version Discriminator | Client Migration Runway | Edge Cacheability | Evaluation |
|---|---|---|---|---|
| Option A: Content Negotiation (`Accept: application/vnd.company.v2+json`) | HTTP `Accept` header | 60 days | Complex (requires `Vary: Accept`) | Rejected: Merchants misconfigure headers (INC-1980); 60 days too abrupt. |
| Option B: Query Parameter (`?api-version=2.0`) | Query string | 6 months | Poor (conflicts with resource caching) | Rejected: Encourages version sprawl and ad-hoc client scraping. |
| Option C: Major URI Path Prefix + RFC 8594 (Chosen) | Path prefix (`/v1/...` vs `/v2/...`) | 12 months | Optimal (distinct URI pathing) | Selected: Explicit, transparent to proxy logs, supported by dual-run adapter. |


### Result

Option C is selected. Major versions are bound to explicit URI paths. Backward compatibility within `/v2` is maintained through additive-only evolution rules.

---

### Required Mechanisms

#### 1. Task Contract & Versioning Scheme [MC-VC-01]
- **URI Path Contract**:
  - Legacy Active: `https://api.merchantpay.com/v1/orders`
  - Current Major: `https://api.merchantpay.com/v2/orders`
- **Breaking Schema Mutations in v2**:
  1. *Structured Address*: String fields `shipping_address_line1`, `shipping_city` condensed into structured object:
     `"shipping_address": {"line1": "...", "city": "...", "postal_code": "..."}`
  2. *Canonical Identity*: `customer_id` renamed to `account_id` (UUIDv4).
  3. *Monetary Precision*: Floating-point decimals (`"amount": 42.50`) converted strictly to integer cents (`"amount_cents": 4250`).

#### 2. Compatibility & Schema Evolution Rules [MC-CR-01]
- **Permissible Non-Breaking (Minor) Changes**:
  - Adding new optional fields to request bodies.
  - Adding new fields to response bodies (clients must implement open-world parsing / ignore unknown properties).
  - Adding new optional query parameters.
  - Adding new endpoints.
- **Forbidden Breaking (Major) Changes**:
  - Renaming or removing existing fields.
  - Changing a field's data type (e.g. string to object, float to int).
  - Adding new required fields to request payloads.
  - Changing HTTP status codes for existing error conditions.

#### 3. Deprecation & Sunset Protocol (RFC 8594) [MC-DS-01]
Every HTTP response returned by `/v1/orders` must inject standard RFC 8594 headers:
```http
HTTP/1.1 200 OK
**Content-Type:** application/json
**Deprecation:** @1789456200
**Sunset:** Wed, 16 Sep 2027 00:00:00 GMT
**Link:** <https://developer.merchantpay.com/docs/migration-v1-to-v2>; rel="sunset"; type="text/html"

• Sunset Date: Exactly 365 days (12 months) following the official production GA of v2.0 (2027-09-16).

4. Dual-Run Translation Adapter [MC-TA-01]

• Ingress Gateway Translation: An in-memory gateway adapter intercepts /v1/orders requests, transforms legacy payloads to canonical v2 internal representations, invokes the core service, and back-translates the v2 response to the v1 JSON format.
• Latency Budget: Adapter transformation overhead p95 <= 8 ms.
• Error Transparency: v2 business errors map deterministically back to v1 error code equivalents.

Invariants and Contracts

Major URI Path Segmentation [INV-VER-01]
  Breaking contract modifications must be isolated under a new major URI path segment (`/v2/`).
  Applying breaking changes in-place under `/v1/` is strictly prohibited.

12-Month Sunset Guarantee [INV-VER-02]
  Deprecated major API versions must remain operational for a minimum of 365 calendar days
  from the formal publication of the RFC 8594 `Sunset` header.

Open-World Client Parsing Requirement [INV-VER-03]
  Client SDKs and merchant documentation must explicitly mandate tolerant JSON parsing.
  Clients that break upon encountering unannounced additive fields are non-compliant.

Explicit Unknowns

• Third-party ERP vendor release cycles for on-premise NetSuite / SAP connector updates (G-1).
• Rate of automated merchant webhook endpoint migration under self-serve partner developer portals (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against API versioning standards:

• Versioning Strategy: PASS. Major URI path segment chosen; content negotiation rejected.
• Header Conformance: PASS. RFC 8594 Deprecation, Sunset, and Link headers fully specified.
• Migration Feasibility: PASS. 12-month runway and dual-run translation adapter protect merchants.
• Evolution Clarity: PASS. Permissible additive vs forbidden breaking changes explicitly cataloged.

Open Decisions

• DEC-VER-01: Alex Mercer to determine whether high-volume partners (> 10,000 orders/day) receive proactive outreach alerts if still calling v1 90 days prior to sunset (Owner: Alex Mercer).

Next steps

1. Sarah Chen reviews the v2.0 OpenAPI 3.1.0 specification with the Merchant Advisory Council.
2. Platform team deploys the bidirectional /v1-to-/v2 translation adapter at the API gateway layer.
3. Configure gateway response policies to inject RFC 8594 Deprecation and Sunset headers on all /v1 endpoints.