API Versioning Pattern | Bootspring Docs

Implement sustainable API versioning strategies using URL paths, headers, or content negotiation with deprecation handling and documentation.

Overview#

API versioning allows you to evolve your API while maintaining backward compatibility for existing clients. This pattern covers multiple versioning strategies and their implementation in Next.js.

When to use:

Making breaking changes to API responses
Supporting multiple client versions simultaneously
Gradual API evolution over time
Long-term API maintenance

Key features:

URL-based versioning (most common)
Header-based versioning (cleaner URLs)
Content negotiation (flexible)
Deprecation notices and sunset headers

Code Example#

URL-Based Versioning#

// app/api/v1/users/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { prisma } from '@/lib/db'

// V1 API - returns basic user data
export async function GET() {
  const users = await prisma.user.findMany({
    select: {
      id: true,
      name: true,
      email: true
    }
  })

  return NextResponse.json(users)
}

// app/api/v2/users/route.ts
// V2 API - returns extended user data with different structure
export async function GET() {
  const users = await prisma.user.findMany({
    select: {
      id: true,
      name: true,
      email: true,
      createdAt: true,
      profile: {
        select: {
          avatar: true,
          bio: true
        }
      }
    }
  })

  // V2 uses different response format
  return NextResponse.json({
    data: users,
    meta: {
      total: users.length,
      version: 'v2'
    }
  })
}

Shared Version Logic#

// lib/api/versions.ts
import { NextResponse } from 'next/server'

export type ApiVersion = 'v1' | 'v2' | 'v3'

interface VersionedResponse<T> {
  v1: (data: T) => object
  v2: (data: T) => object
  v3?: (data: T) => object
}

export function formatResponse<T>(
  version: ApiVersion,
  data: T,
  formatters: VersionedResponse<T>
) {
  const formatter = formatters[version]
  if (!formatter) {
    throw new Error(`Unsupported API version: ${version}`)
  }
  return formatter(data)
}

// Usage example
// lib/api/users/formatters.ts
import { User } from '@prisma/client'

export const userFormatters = {
  v1: (user: User) => ({
    id: user.id,
    name: user.name,
    email: user.email
  }),

  v2: (user: User & { profile?: { avatar?: string } }) => ({
    id: user.id,
    displayName: user.name, // renamed field
    email: user.email,
    avatar: user.profile?.avatar ?? null,
    createdAt: user.createdAt.toISOString()
  })
}

Header-Based Versioning#

// middleware.ts
import { NextRequest, NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const version = request.headers.get('API-Version') ?? 'v1'
  const validVersions = ['v1', 'v2', 'v3']

  if (!validVersions.includes(version)) {
    return NextResponse.json(
      { error: `Invalid API version: ${version}` },
      { status: 400 }
    )
  }

  // Add version to request headers for route handlers
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-api-version', version)

  return NextResponse.next({
    request: { headers: requestHeaders }
  })
}

export const config = {
  matcher: '/api/:path*'
}

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { formatResponse } from '@/lib/api/versions'
import { userFormatters } from '@/lib/api/users/formatters'

export async function GET(request: NextRequest) {
  const version = request.headers.get('x-api-version') as 'v1' | 'v2'

  const users = await prisma.user.findMany({
    include: version === 'v2' ? { profile: true } : undefined
  })

  const formatted = users.map(user =>
    formatResponse(version, user, userFormatters)
  )

  const response = NextResponse.json(formatted)
  response.headers.set('API-Version', version)

  return response
}

Content Negotiation Versioning#

// lib/api/content-negotiation.ts
import { NextRequest } from 'next/server'

export function parseAcceptHeader(request: NextRequest): {
  version: string
  format: string
} {
  const accept = request.headers.get('Accept') ?? 'application/json'

  // Parse: application/vnd.myapi.v2+json
  const match = accept.match(/application\/vnd\.myapi\.v(\d+)\+(\w+)/)

  if (match) {
    return {
      version: `v${match[1]}`,
      format: match[2]
    }
  }

  return { version: 'v1', format: 'json' }
}

// app/api/users/route.ts
export async function GET(request: NextRequest) {
  const { version, format } = parseAcceptHeader(request)

  const users = await prisma.user.findMany()

  const formatted = users.map(user =>
    formatResponse(version as 'v1' | 'v2', user, userFormatters)
  )

  const contentType = `application/vnd.myapi.${version}+${format}`

  return new Response(JSON.stringify(formatted), {
    headers: {
      'Content-Type': contentType
    }
  })
}

Version Deprecation#

// lib/api/deprecation.ts
import { NextResponse } from 'next/server'

interface DeprecationInfo {
  deprecated: boolean
  sunset?: string // ISO date when version will be removed
  successor?: string // Recommended version to migrate to
  message?: string
}

const versionStatus: Record<string, DeprecationInfo> = {
  v1: {
    deprecated: true,
    sunset: '2024-12-31',
    successor: 'v2',
    message: 'Please migrate to v2 API before December 31, 2024'
  },
  v2: { deprecated: false },
  v3: { deprecated: false }
}

export function addDeprecationHeaders(
  response: NextResponse,
  version: string
): NextResponse {
  const info = versionStatus[version]

  if (info?.deprecated) {
    response.headers.set('Deprecation', 'true')
    if (info.sunset) {
      response.headers.set('Sunset', info.sunset)
    }
    if (info.message) {
      response.headers.set('X-Deprecation-Notice', info.message)
    }
    if (info.successor) {
      response.headers.set(
        'Link',
        `</api/${info.successor}>; rel="successor-version"`
      )
    }
  }

  return response
}

// Usage in route handler
export async function GET(request: NextRequest) {
  const version = request.headers.get('x-api-version') ?? 'v1'

  const data = await fetchData()

  let response = NextResponse.json(data)
  response = addDeprecationHeaders(response, version)

  return response
}

Version-Specific Middleware#

// lib/api/version-middleware.ts
import { NextRequest, NextResponse } from 'next/server'

type Handler = (req: NextRequest) => Promise<NextResponse>
type VersionedHandlers = Record<string, Handler>

export function createVersionedHandler(handlers: VersionedHandlers) {
  return async (request: NextRequest) => {
    const version = request.headers.get('x-api-version') ?? 'v1'

    const handler = handlers[version]
    if (!handler) {
      return NextResponse.json(
        {
          error: 'Unsupported API version',
          supportedVersions: Object.keys(handlers)
        },
        { status: 400 }
      )
    }

    return handler(request)
  }
}

// app/api/products/route.ts
import { createVersionedHandler } from '@/lib/api/version-middleware'

const v1Handler = async (request: NextRequest) => {
  const products = await prisma.product.findMany()
  return NextResponse.json(products)
}

const v2Handler = async (request: NextRequest) => {
  const products = await prisma.product.findMany({
    include: { variants: true, reviews: true }
  })
  return NextResponse.json({
    data: products,
    included: { totalCount: products.length }
  })
}

export const GET = createVersionedHandler({
  v1: v1Handler,
  v2: v2Handler
})

API Documentation per Version#

// lib/api/openapi.ts
import { OpenAPIObject } from 'openapi3-ts/oas31'

export const openApiSpecs: Record<string, OpenAPIObject> = {
  v1: {
    openapi: '3.1.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API v1 (deprecated)'
    },
    paths: {
      '/api/v1/users': {
        get: {
          summary: 'List users',
          responses: {
            '200': {
              description: 'List of users',
              content: {
                'application/json': {
                  schema: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/UserV1' }
                  }
                }
              }
            }
          }
        }
      }
    },
    components: {
      schemas: {
        UserV1: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            name: { type: 'string' },
            email: { type: 'string' }
          }
        }
      }
    }
  },
  v2: {
    openapi: '3.1.0',
    info: {
      title: 'My API',
      version: '2.0.0',
      description: 'API v2 (current)'
    },
    // ... v2 spec
  }
}

// app/api/docs/[version]/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { openApiSpecs } from '@/lib/api/openapi'

export async function GET(
  request: NextRequest,
  { params }: { params: { version: string } }
) {
  const spec = openApiSpecs[params.version]

  if (!spec) {
    return NextResponse.json(
      { error: 'Version not found' },
      { status: 404 }
    )
  }

  return NextResponse.json(spec)
}

Usage Instructions#

Choose versioning strategy: URL paths (recommended for public APIs), headers (cleaner), or content negotiation
Create version formatters: Define how data is transformed for each version
Implement route handlers: Use versioned handlers or separate route files
Add deprecation handling: Notify clients of deprecated versions
Document each version: Maintain separate documentation per version

Best Practices#

Start with v1 - Plan for versioning from the beginning
Use semantic versioning - Major versions for breaking changes
Deprecate gracefully - Give clients time to migrate
Document differences - Clearly explain what changed between versions
Support multiple versions - Keep at least 2 versions active
Set sunset dates - Communicate when versions will be removed
Monitor usage - Track which versions clients use

Route Handler - API endpoint implementation
Middleware - Request preprocessing
Error Handling - Consistent error responses
OpenAPI - API documentation