Edge Function API Versioning Guide

​

Overview

​

Quick Start — Adding Versioning to a Function

​

1. Define a contract

/** V1 request */
export interface MyFunctionV1Request {
  organization_id: string;
  name: string;
}

/** V1 response */
export interface MyFunctionV1Response {
  success: boolean;
  id: string;
}

​

2. Wrap with withVersioning

import { withVersioning } from '../_shared/versioning.ts';

async function v1Handler(req: Request): Promise<Response> {
  // existing logic
}

Deno.serve(withVersioning('my-function', { v1: v1Handler }));

​

3. (Optional) Add a v2

async function v2Handler(req: Request): Promise<Response> {
  // new logic
}

Deno.serve(
  withVersioning('my-function', { v1: v1Handler, v2: v2Handler }, {
    deprecated: {
      v1: { sunset: '2026-09-01', successor: 'v2' },
    },
  }),
);

​

How It Works

1. Caller sends X-API-Version: v1 header.
2. withVersioning looks up handlers['v1'].
3. If found → executes handler; if deprecated → merges Deprecation / Sunset / Link headers.
4. If not found → returns 400 with migration guidance (PF-07 error envelope).
5. If no header → defaults to highest version key.

​

Feature Flag

​

Contract Conventions

• File: _shared/contracts/{function-name}.contract.ts
• Naming: {FunctionName}V{N}Request, {FunctionName}V{N}Response
• Major-only semver surface: v1, v2 — minor/patch changes stay backward-compatible
• Re-export all contracts from _shared/contracts/index.ts

​

Deprecation Headers

​

CI Contract Validation

• Additions (new exports): non-breaking ✅
• Removals (deleted exports): breaking ❌ — bump major version

​

Consumer Obligations

1. Send X-API-Version header or accept the default (latest stable).
2. Handle 400 responses with migration guidance when a version is unsupported.
3. Respect Sunset dates by migrating before the removal deadline.
4. Monitor Deprecation headers in responses.

​

Related Documents

• PF-89 Spec
• PF-89 Integration
• API Contracts
• Event Contracts