Skip to main content
Status: 📝 Planned
Spec: specs/pf/specs/PF-89-api-versioning-edge-function-lifecycle.md
Plan: specs/pf/plans/PF-89-api-versioning-edge-function-lifecycle-PLAN.md
Last updated: 2026-03-24

​
Purpose

Document how Edge Functions expose application-level API versions (header negotiation), how contracts are stored and validated in CI, and how deprecation signals integrate with observability (PF-48) and system health UI (PF-36).

​
Scope

  • In scope: X-API-Version, withVersioning middleware pattern, supabase/functions/_shared/contracts/, deprecation headers (Deprecation, Sunset, Link), CI contract-diff behavior.
  • Out of scope: Supabase infrastructure path /functions/v1/ (platform-managed); GraphQL; auto-generated OpenAPI in Phase 1–4 (spec deferred).

​
Consumer obligations (all cores)

  1. For new or migrated versioned functions: send X-API-Version or accept documented default (latest stable).
  2. Handle 400 responses with migration guidance when version unsupported.
  3. Respect Sunset by migrating before removal date; monitor PF-36 / Sentry warnings when enabled.

​
Auth and tenant isolation

  • Version negotiation is orthogonal to JWT and verifyOrgAccess() / verifyOrgRole() — no tenant data in version headers.
  • Contract files are server-side only; never expose raw internal types to clients.

​
Checklist (implementation)

  • Pilot functions wrapped with withVersioning (opt-in).
  • docs/development/api-versioning-guide.md published.
  • API_CONTRACTS.md updated to cross-reference Edge header versioning.
  • GitHub Actions contract validation runs on PRs touching *.contract.ts or pilot functions.