JSON API Versioning: URL, Header, Media Type & Breaking Changes

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 20, 2026

JSON API versioning controls how breaking changes to response structure are communicated to clients — the three main strategies are URL path versioning (/v1/users), Accept header versioning (Accept: application/vnd.api+json;version=2), and query parameter versioning (?api_version=2), each with different tradeoffs in discoverability and cache behavior. URL path versioning is the most widely adopted strategy — used by Stripe (/v1/), Twilio (/2010-04-01/), and GitHub (/v3/) — because it is explicit in logs, cache-friendly, and requires no client header configuration; it is the recommended default for public JSON APIs. This guide covers URL, header, and media-type versioning strategies, what constitutes a breaking vs non-breaking JSON change, semantic versioning for APIs, sunset headers for deprecation, and evolving JSON schemas with backward compatibility.

URL Path Versioning: /v1/, /v2/, Date-Based

URL segment versioning is the dominant strategy for public JSON APIs — embed the version identifier directly in the URL path before the resource name. The version is explicit in logs, visible in browser dev tools, bookmark-friendly, and cached correctly by CDNs without any special configuration because different versions have different URLs. Stripe, GitHub, Twilio, and the majority of public REST APIs use this approach.

Integer versioning (/v1/, /v2/) increments the major version with each set of breaking changes. Date-based versioning (Stripe's YYYY-MM-DD pattern) pins each API key to the dated snapshot active at creation — Stripe ships /v1/charges but internally routes requests through a dated compatibility layer. The cons of URL versioning: the same logical resource exists at multiple URLs (/v1/users/123 and /v2/users/123), which violates strict REST resource identity; routing configuration must be duplicated per version; and running multiple live versions in parallel increases maintenance burden.

// Express.js — separate routers per version
const express = require('express')
const app = express()

// Shared service layer — version-agnostic data access
const { getUserById } = require('./services/users')

// v1 router — old shape: single "name" field
const v1Router = express.Router()
v1Router.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id)
  res.json({ id: user.id, name: user.fullName, email: user.email })
})

// v2 router — new shape: firstName/lastName split + createdAt
const v2Router = express.Router()
v2Router.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id)
  res.json({
    id: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    createdAt: user.createdAt,
  })
})

// Mount version routers — URLs: /v1/users/:id and /v2/users/:id
app.use('/v1', v1Router)
app.use('/v2', v2Router)

// ── Next.js App Router — versioned directories ──────────────────
// app/api/v1/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { getUserById } from '@/lib/services/users'

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const user = await getUserById(params.id)
  // v1 shape — add deprecation headers
  const res = NextResponse.json({
    id: user.id,
    name: `${user.firstName} ${user.lastName}`,
    email: user.email,
  })
  res.headers.set('Sunset', 'Sat, 01 Jan 2028 00:00:00 GMT')
  res.headers.set('Deprecation', 'true')
  res.headers.set('Link', '</api/v2/users/' + params.id + '>; rel="successor-version"')
  return res
}

// app/api/v2/users/[id]/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const user = await getUserById(params.id)
  // v2 shape — current version, no deprecation headers
  return NextResponse.json({
    id: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    createdAt: user.createdAt,
  })
}

// ── Stripe date-based versioning pattern ───────────────────────
// Client pins version via header: Stripe-Version: 2024-06-20
// Each API key is pinned to the version active at key creation
// Stripe routes requests through a dated compatibility adapter:
// GET /v1/charges → internal router checks Stripe-Version header
//   → applies compatibility transforms for that dated version
// New dated version ships when breaking changes are introduced
// Existing keys remain on old dated version automatically

The architectural key: share all business logic and data access in a version-agnostic service layer. Route handlers apply only the version-specific JSON shape transformation. This avoids duplicating database queries while keeping versioned response contracts independent and independently testable.

Header Versioning: Accept and Custom Headers

Header versioning signals the desired API version through an HTTP request header rather than the URL. The URL stays stable (/api/users/123) while the response shape varies by header value. Two common patterns: the standard Accept header with a vendor MIME type (Accept: application/vnd.api+json;version=2), and a custom header like X-API-Version: 2 or Accept-Version: 2. Header versioning is semantically purer from a REST perspective — the same resource URI returns different representations based on client negotiation — but it adds operational complexity.

# ── Accept header versioning ────────────────────────────────────
# Client requests v2 representation via vendor MIME type
GET /api/users/123 HTTP/1.1
Accept: application/vnd.myapi.v2+json

# Server response — must include Vary to prevent cache poisoning
HTTP/1.1 200 OK
Content-Type: application/vnd.myapi.v2+json
Vary: Accept

{"id":"123","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}

# ── Custom X-API-Version header ──────────────────────────────────
GET /api/users/123 HTTP/1.1
X-API-Version: 2

HTTP/1.1 200 OK
Content-Type: application/json
Vary: X-API-Version

{"id":"123","firstName":"Ada","lastName":"Lovelace","email":"ada@example.com"}

# ── JSON:API registered MIME type ────────────────────────────────
# application/vnd.api+json is the IANA-registered media type for the
# JSON:API specification (jsonapi.org). Not to be confused with
# custom vendor types like application/vnd.myapi.v2+json.
GET /api/users/123 HTTP/1.1
Accept: application/vnd.api+json

# ── Next.js App Router — header versioning in a single route ────
// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { getUserById } from '@/lib/services/users'
import { serializeV1, serializeV2 } from '@/lib/serializers/users'

function parseVersion(request: NextRequest): number {
  // Try X-API-Version header first
  const versionHeader = request.headers.get('x-api-version')
  if (versionHeader) return parseInt(versionHeader, 10)

  // Fall back to parsing Accept header
  const accept = request.headers.get('accept') ?? ''
  const match = accept.match(/version=(d+)/)
  if (match) return parseInt(match[1], 10)

  return 1 // default to v1
}

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const version = parseVersion(request)
  const user = await getUserById(params.id)

  if (version === 1) {
    const res = NextResponse.json(serializeV1(user))
    res.headers.set('Vary', 'X-API-Version, Accept')
    res.headers.set('Sunset', 'Sat, 01 Jan 2028 00:00:00 GMT')
    return res
  }

  if (version === 2) {
    const res = NextResponse.json(serializeV2(user))
    res.headers.set('Vary', 'X-API-Version, Accept')
    return res
  }

  // Unsupported version — 406 Not Acceptable
  return NextResponse.json(
    { error: 'Unsupported API version', supported: [1, 2] },
    { status: 406, headers: { 'Vary': 'X-API-Version, Accept' } }
  )
}

Critical cache consideration: without Vary: X-API-Version (or Vary: Accept), a CDN may cache a v1 response and serve it to v2 clients — a silent correctness bug that is difficult to diagnose. Always set Vary to include every request header that influences the response shape. Header versioning also cannot be tested by pasting a URL into a browser — use curl (curl -H 'X-API-Version: 2' https://api.example.com/users/123) or an HTTP client like Postman.

Breaking vs Non-Breaking JSON Schema Changes

The most important design decision in API versioning is distinguishing breaking changes (require a major version bump) from additive changes (safe to ship without a version bump). The open/closed principle applied to JSON schemas: schemas should be open for extension (new optional fields) and closed for modification (existing fields stay stable).

// ── BREAKING changes — always require a major version bump ──────

// 1. Removing a field — clients accessing response.name crash
// v1 response: { "id": "123", "name": "Ada Lovelace", "email": "ada@example.com" }
// v2 response: { "id": "123", "email": "ada@example.com" }  ← name removed

// 2. Renaming a field — same as remove + add
// v1: { "userId": "123" }   v2: { "id": "123" }  ← renamed

// 3. Changing a field type — string to number breaks JSON.parse expectations
// v1: { "id": "123" }    // string ID
// v2: { "id": 123 }      // number ID — breaks clients doing strict equality

// 4. Changing date format — breaks date parsing
// v1: { "createdAt": 1716163200 }         // Unix timestamp (seconds)
// v2: { "createdAt": "2026-05-20T00:00:00Z" }  // ISO-8601 — different type

// 5. Making an optional request field required — existing requests fail
// v1 POST /orders body: { "productId": "p1" }  ← region optional
// v2 POST /orders body: { "productId": "p1", "region": "us-east-1" }  ← required

// 6. Removing enum values — clients may receive an unhandled value
// v1: status can be "pending" | "active" | "legacy"
// v2: status can be "pending" | "active"  ← "legacy" removed

// ── NON-BREAKING (additive) changes — safe without version bump ──

// 1. Adding a new optional field — well-behaved clients ignore unknown fields
// v1: { "id": "123", "name": "Ada" }
// v2: { "id": "123", "name": "Ada", "displayName": "Ada L." }  ← new optional

// 2. Adding new enum values — IF clients handle unknown values gracefully
// v1: status: "pending" | "active"
// v2: status: "pending" | "active" | "suspended"  ← new value added
// Client code must handle: if (status === "active") { ... } else { /* handle unknown */ }

// 3. Relaxing validation — optional field was required
// v1 POST: { "name": "Ada", "phone": "+1555000" }  ← phone required
// v2 POST: { "name": "Ada" }  ← phone now optional — existing requests still valid

// 4. Adding a new optional request parameter
// v1 GET /users?limit=20
// v2 GET /users?limit=20&includeDeleted=true  ← new optional param

// ── Open/closed principle in JSON Schema ────────────────────────
// Correct: additionalProperties defaults to true — ignore unknown fields
{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" }
  }
  // No "additionalProperties: false" — clients MUST accept new fields
}

// Wrong: this breaks clients when you add a new field
{
  "type": "object",
  "properties": { "id": { "type": "string" }, "name": { "type": "string" } },
  "additionalProperties": false  // ← never use false on API responses
}

The robustness principle (Postel's Law) applied to JSON clients: be conservative in what you send, liberal in what you accept. Well-behaved API clients must ignore unknown fields in JSON responses — failing on unknown fields makes every additive change a breaking change for that client. When writing JSON schema validation for request bodies you control, additionalProperties: false is fine (strict validation of incoming data); never apply it to response schemas that clients parse.

Semantic Versioning for JSON APIs

Semantic versioning (SemVer: MAJOR.MINOR.PATCH) maps cleanly onto JSON API change categories. MAJOR = breaking change requiring client migration; MINOR = new backwards-compatible feature (new optional field, new endpoint); PATCH = bug fix with no contract change. In practice, expose only the MAJOR version in the URL (/v1/, /v2/) and communicate MINOR and PATCH changes through an API changelog — full semver URLs like /v1.2.3/users create operational complexity with no benefit to clients.

// ── SemVer applied to JSON API changes ──────────────────────────

// MAJOR bump (1.x.x → 2.0.0) — breaking, clients MUST update
// Examples:
//   - Removed field "name" → split into "firstName" + "lastName"
//   - Changed "id" type from string to integer
//   - Made "region" required in POST /orders
//   - Removed endpoint DELETE /v1/legacy-export

// MINOR bump (1.0.x → 1.1.0) — additive, backwards-compatible
// Examples:
//   - Added optional "displayName" field to user responses
//   - Added new endpoint GET /v1/users/:id/preferences
//   - Added new optional query param ?includeMetadata=true
//   - Added new enum value "suspended" to status field

// PATCH bump (1.0.0 → 1.0.1) — bug fix, no contract change
// Examples:
//   - Fixed: createdAt returned UTC+1 instead of UTC
//   - Fixed: nextCursor was null on last page instead of omitted
//   - Fixed: error response missing "code" field for 500 errors

// ── API changelog JSON endpoint ─────────────────────────────────
// Serve a machine-readable changelog at /api/changelog.json
// Clients and monitoring tools can poll this for version info

// GET /api/changelog.json
{
  "currentVersion": "2",
  "versions": [
    {
      "version": "2",
      "semver": "2.0.0",
      "released": "2026-05-20",
      "status": "current",
      "changes": [
        { "type": "breaking", "description": "Split 'name' field into 'firstName' and 'lastName'" },
        { "type": "breaking", "description": "Changed 'id' from string to UUID string format" },
        { "type": "added", "description": "Added 'createdAt' field to user responses" }
      ]
    },
    {
      "version": "1",
      "semver": "1.3.0",
      "released": "2024-01-15",
      "status": "deprecated",
      "sunset": "2028-01-01T00:00:00Z",
      "successor": "/v2/",
      "changes": []
    }
  ]
}

// ── Version negotiation ──────────────────────────────────────────
// Clients can request the latest supported version:
// GET /api/changelog.json → find highest non-deprecated version
// Or use an explicit "latest" alias (redirect to current major):
// GET /api/latest/users/123 → 301 Redirect → /api/v2/users/123

Publishing a /api/changelog.json endpoint makes version information programmatically accessible — monitoring tools, API gateways, and SDK generators can discover the current version and available migrations without scraping documentation HTML. Version negotiation through a changelog JSON is particularly useful for internal microservices where consumers can auto-detect and adapt to the latest supported version.

Deprecation: Sunset Header and Migration Path

A structured deprecation workflow gives clients machine-readable signals and adequate notice to migrate before an API version is retired. The standard HTTP headers for deprecation signaling are Sunset (RFC 8594), Deprecation (IETF draft RFC 8594 companion), and Link with the successor-version relation. These headers should appear on every response from the deprecated version — not just on error responses — so API monitoring tools and client SDKs can detect them automatically.

# ── Deprecation headers on every v1 response ────────────────────
HTTP/1.1 200 OK
Content-Type: application/json
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Deprecation: true
Link: </v2/users>; rel="successor-version",
      <https://docs.example.com/migration/v1-to-v2>; rel="deprecation"

# Sunset      — RFC 8594: retirement date (machine-readable deadline)
# Deprecation — IETF draft: signals this endpoint is deprecated
# Link rel="successor-version" — where to migrate to
# Link rel="deprecation" — human-readable migration documentation

# ── After sunset date — return 410 Gone ─────────────────────────
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "API version retired",
  "message": "v1 was retired on 2028-01-01. Migrate to v2: https://docs.example.com/migration/v1-to-v2",
  "successor": "https://api.example.com/v2/users"
}

// ── Express.js — deprecation middleware for v1 ──────────────────
function deprecateV1(req, res, next) {
  const sunsetDate = new Date('2028-01-01T00:00:00.000Z')

  // After sunset date — return 410 Gone
  if (new Date() > sunsetDate) {
    return res.status(410).json({
      error: 'API version retired',
      message: 'v1 was retired on 2028-01-01. Migrate to v2.',
      successor: `https://api.example.com/v2${req.path}`,
    })
  }

  // Before sunset — add deprecation headers to every response
  res.setHeader('Sunset', 'Sat, 01 Jan 2028 00:00:00 GMT')
  res.setHeader('Deprecation', 'true')
  res.setHeader('Link', [
    `</v2${req.path}>; rel="successor-version"`,
    `<https://docs.example.com/migration/v1-to-v2>; rel="deprecation"`,
  ].join(', '))
  next()
}

app.use('/v1', deprecateV1, v1Router)

// ── Logging deprecated endpoint usage ───────────────────────────
// Track which clients still use deprecated v1 to send targeted reminders
function logDeprecatedUsage(req, res, next) {
  console.log(JSON.stringify({
    event: 'deprecated_api_access',
    version: 'v1',
    path: req.path,
    apiKey: req.headers['x-api-key'],
    userAgent: req.headers['user-agent'],
    timestamp: new Date().toISOString(),
  }))
  next()
}

app.use('/v1', logDeprecatedUsage, deprecateV1, v1Router)

Deprecation timeline best practices: announce the deprecation date at least 6 months before the sunset date (12 months for widely-used public APIs); begin adding Sunset and Deprecation headers immediately after announcement; publish side-by-side migration examples for every breaking change; email all registered API consumers with the timeline; monitor deprecated endpoint traffic and send targeted migration reminders to teams still using it one month and one week before sunset.

Backward-Compatible JSON Schema Evolution

Backward-compatible JSON schema evolution — shipping improvements to your API without breaking existing clients — is the primary mechanism for extending an API within a major version. The core techniques are: additive-only field additions, the expand-and-contract pattern for field migration, oneOf/anyOf for polymorphic response shapes, and field aliasing during transitions.

// ── Additive field addition (safe — no version bump needed) ─────
// Before: GET /v1/users/123
{ "id": "123", "name": "Ada Lovelace", "email": "ada@example.com" }

// After adding optional "displayName" field:
{ "id": "123", "name": "Ada Lovelace", "email": "ada@example.com", "displayName": "Ada L." }
// Existing clients ignore "displayName" — no breaking change

// ── Expand-and-contract for field renaming ──────────────────────
// Goal: rename "name" → "firstName" + "lastName" in v2
// Step 1 (minor release in v1): add new fields alongside old (expand)
{
  "id": "123",
  "name": "Ada Lovelace",          // ← keep old field, mark deprecated in changelog
  "firstName": "Ada",              // ← add new fields
  "lastName": "Lovelace",
  "email": "ada@example.com"
}
// Step 2: clients migrate to use firstName/lastName
// Step 3 (v2 major release): remove old "name" field (contract)
{ "id": "123", "firstName": "Ada", "lastName": "Lovelace", "email": "ada@example.com" }

// ── oneOf / anyOf for polymorphic responses ─────────────────────
// When a field can return different shapes, use JSON Schema oneOf
// GET /v1/payment — returns either card or bank_transfer shape

// JSON Schema with oneOf:
{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "method": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": { "const": "card" },
            "last4": { "type": "string" },
            "brand": { "type": "string" }
          },
          "required": ["type", "last4", "brand"]
        },
        {
          "type": "object",
          "properties": {
            "type": { "const": "bank_transfer" },
            "bankName": { "type": "string" },
            "accountLast4": { "type": "string" }
          },
          "required": ["type", "bankName", "accountLast4"]
        }
      ]
    }
  }
}

// Client discriminates on "type" field — safe to add new oneOf variants
// in a minor release without breaking existing clients

// ── Field aliasing during transition ────────────────────────────
// Return both old and new field names during migration window
// Express.js serializer with aliasing:
function serializeUserTransition(user) {
  return {
    // Old field (deprecated) — keep for transition period
    name: `${user.firstName} ${user.lastName}`,
    // New fields — clients migrate to these
    firstName: user.firstName,
    lastName: user.lastName,
    // Unchanged fields
    id: user.id,
    email: user.email,
  }
}

// ── Handling unknown enum values in clients ──────────────────────
// JavaScript — defensive enum handling
function getStatusLabel(status) {
  const labels = {
    pending: 'Pending',
    active: 'Active',
    suspended: 'Suspended',
  }
  // Return a fallback for unknown future enum values
  return labels[status] ?? `Unknown (${status})`
}

// TypeScript — use string type with known values
type UserStatus = 'pending' | 'active' | 'suspended' | (string & {})
// The (string & {}) intersection allows unknown values without losing type hints

The expand-and-contract pattern is the most practical technique for evolving JSON schemas without major version bumps. The transition window (time between expanding and contracting) should be at least one full release cycle — long enough for all clients to migrate. Use your API analytics to confirm client adoption of the new field before removing the old one.

Versioning in Next.js App Router and OpenAPI

Next.js App Router supports multiple versioning patterns. URL path versioning with explicit /v1/ and /v2/ path segments is the most straightforward: create versioned route files at app/api/v1/route.ts and app/api/v2/route.ts. Route groups (app/(v1)/api/route.ts) are a file-organization tool but do not change the URL structure — avoid them for API versioning where the version should be visible in the URL. OpenAPI and Zod-to-OpenAPI enable generating version-specific JSON specs served at /api/v1/openapi.json.

// ── File structure for URL path versioning ───────────────────────
// app/
//   api/
//     v1/
//       users/
//         [id]/
//           route.ts     ← GET /api/v1/users/:id
//       orders/
//         route.ts       ← GET /api/v1/orders
//     v2/
//       users/
//         [id]/
//           route.ts     ← GET /api/v2/users/:id
//       orders/
//         route.ts       ← GET /api/v2/orders
//   lib/
//     services/
//       users.ts         ← shared data access
//     serializers/
//       users.ts         ← version-specific JSON transforms

// lib/serializers/users.ts — version-specific JSON shapes
import type { UserRecord } from '@/lib/services/users'

export function serializeUserV1(user: UserRecord) {
  return {
    id: user.id,
    name: `${user.firstName} ${user.lastName}`,
    email: user.email,
  }
}

export function serializeUserV2(user: UserRecord) {
  return {
    id: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    createdAt: user.createdAt,
  }
}

// ── OpenAPI versioning with Zod and zod-to-openapi ──────────────
// app/api/v1/openapi.json/route.ts — serve version-specific OpenAPI spec
import { NextResponse } from 'next/server'
import { OpenApiGeneratorV3, OpenAPIRegistry } from '@asteasolutions/zod-to-openapi'
import { z } from 'zod'

const registry = new OpenAPIRegistry()

// v1 user schema
const UserV1Schema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})

registry.registerPath({
  method: 'get',
  path: '/api/v1/users/{id}',
  summary: 'Get user by ID (v1)',
  tags: ['Users'],
  responses: {
    200: {
      description: 'User resource',
      content: { 'application/json': { schema: UserV1Schema } },
    },
  },
})

export async function GET() {
  const generator = new OpenApiGeneratorV3(registry.definitions)
  const spec = generator.generateDocument({
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
  })
  return NextResponse.json(spec)
}

// ── AWS API Gateway stage variable versioning ────────────────────
// API Gateway uses "stages" for versioning: prod, v1, v2
// Stage variables let Lambda functions read the active version:
//   GET https://abc123.execute-api.us-east-1.amazonaws.com/v1/users
// Stage variable: stageVariables.apiVersion = "v1"
// Lambda handler reads: const version = event.stageVariables?.apiVersion ?? 'v1'

For OpenAPI spec versioning, generate separate openapi.json files per major API version and serve them at versioned paths. API documentation tools (Swagger UI, Redoc, Scalar) can be configured to show version tabs. When using an API gateway (AWS API Gateway, Kong, Nginx), configure version routing at the gateway layer so downstream services do not need to handle URL version parsing themselves.

Key Terms

breaking change

Any modification to a JSON API that causes existing clients to fail or produce incorrect results. Examples: removing a field from a response, renaming a field, changing a field's data type (e.g., string to number), making an optional request field required, or removing an endpoint. Breaking changes require a major version bump (v1 -> v2) so clients can choose when to migrate.

additive change

A backwards-compatible modification to a JSON API that adds new capabilities without altering or removing existing ones. Adding a new optional response field, a new endpoint, or a new optional request parameter are all additive changes. Additive changes do not require a version bump — existing clients continue working unchanged because well-behaved clients ignore unknown JSON fields (the open/closed principle).

content negotiation

The HTTP mechanism by which a client and server agree on the representation format for a resource. The client advertises supported formats via the Accept request header; the server responds with the Content-Type header identifying the chosen format. In header-based API versioning, content negotiation is used to select the API version — the client sends Accept: application/vnd.myapi.v2+json and the server responds with the v2 JSON representation. The Vary response header instructs caches to store separate responses per Accept value.

Sunset header

An HTTP response header defined in RFC 8594 that communicates the date and time after which a resource or API version will no longer be available. Format: Sunset: <HTTP-date>, for example Sunset: Sat, 01 Jan 2028 00:00:00 GMT. It is machine-readable — API monitoring tools, client SDK libraries, and API gateways can detect it and alert developers automatically. The Sunset header should be included on every response from a deprecated endpoint, paired with the Deprecation header and a Link header pointing to the successor version.

API changelog

A versioned record of all changes made to an API, organized by version and change type (breaking, additive, bug fix). An API changelog documents what changed, which version introduced the change, and how clients should migrate. Machine-readable changelog JSON endpoints (/api/changelog.json) allow clients, SDK generators, and monitoring tools to programmatically discover version information without scraping HTML documentation. Stripe publishes one of the most detailed public API changelogs, with every change listed per dated API version.

version pinning

A versioning pattern where each API consumer is locked to a specific API version at account creation or integration time, and continues using that version until explicitly opting into a newer one. Stripe's date-based versioning implements version pinning: each API key is associated with the Stripe API version active on the key's creation date. New Stripe API versions are released when breaking changes ship; existing API keys remain on their pinned version. This decouples the server's release schedule from client migration timelines, but requires the server to maintain and test all pinned versions concurrently.

FAQ