Skip to content

versioning.mdx

Latest commit

 

History

History
119 lines (78 loc) · 4.19 KB

versioning.mdx

File metadata and controls

119 lines (78 loc) · 4.19 KB
Raw
title Versioning
description Versioning protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

API Versioning Protocol

Defines how API versions are negotiated between client and server.

Supports multiple versioning strategies and deprecation lifecycle management.

Architecture Alignment:

  • Salesforce: URL path versioning (v57.0, v58.0)

  • Stripe: Date-based versioning (2024-01-01)

  • Kubernetes: API group versioning (v1, v1beta1)

  • GitHub: Accept header versioning (application/vnd.github.v3+json)

  • Microsoft Graph: URL path versioning (v1.0, beta)

**Source:** `packages/spec/src/api/versioning.zod.ts`

TypeScript Usage

import { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningConfig, VersioningStrategy } from '@objectstack/spec/api';
import type { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningConfig, VersioningStrategy } from '@objectstack/spec/api';

// Validate data
const result = VersionDefinition.parse(data);

VersionDefinition

Properties

Property Type Required Description
version string ✅ Version identifier (e.g., "v1", "v2beta1", "2025-01-01")
status Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'> ✅ Lifecycle status of this version
releasedAt string ✅ Release date (ISO 8601, e.g., "2025-01-15")
deprecatedAt string optional Deprecation date (ISO 8601). Only set for deprecated/retired versions
sunsetAt string optional Sunset date (ISO 8601). After this date, the version returns 410 Gone
migrationGuide string optional URL to migration guide for upgrading from this version
description string optional Human-readable description or release notes summary
breakingChanges string[] optional List of breaking changes (for preview/new versions)

VersionNegotiationResponse

Properties

Property Type Required Description
current string ✅ Current recommended API version
requested string optional Version requested by the client
resolved string ✅ Resolved API version for this request
supported string[] ✅ All supported version identifiers
deprecated string[] optional Deprecated version identifiers
versions { version: string; status: Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'>; releasedAt: string; deprecatedAt?: string; … }[] optional Full version definitions with lifecycle metadata

VersionStatus

Allowed Values

  • preview
  • current
  • supported
  • deprecated
  • retired

VersioningConfig

Properties

Property Type Required Description
strategy Enum<'urlPath' | 'header' | 'queryParam' | 'dateBased'> ✅ How the API version is specified by clients
current string ✅ The current/recommended API version identifier
default string ✅ Fallback version when client does not specify one
versions { version: string; status: Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'>; releasedAt: string; deprecatedAt?: string; … }[] ✅ All available API versions with lifecycle metadata
headerName string ✅ HTTP header name for version negotiation (header/dateBased strategies)
queryParamName string ✅ Query parameter name for version specification (queryParam strategy)
urlPrefix string ✅ URL prefix before version segment (urlPath strategy)
deprecation { warnHeader: boolean; sunsetHeader: boolean; linkHeader: boolean; rejectRetired: boolean; … } optional Deprecation lifecycle behavior
includeInDiscovery boolean ✅ Include version information in the API discovery endpoint

VersioningStrategy

Allowed Values

  • urlPath
  • header
  • queryParam
  • dateBased