Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

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).
DocumentRelationship
API_CONTRACTS.mdREST path versioning narrative; must stay consistent with Edge header versioning once implemented
CROSS_CORE_INTEGRATIONS.mdAll cores consume Edge Functions — versioning affects integration testing and rollout
EVENT_CONTRACTS.mdPF-48 may consume deprecated-usage events — payloads must be identifier-only (no PHI)

​
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.