Bootspring
HomeGet Started

API Versioning Pattern

Sustainable API versioning using URL paths, headers, or content negotiation with deprecation handling, response formatters, and per-version documentation.

What's Included#

  • URL-based versioning with separate route files per version
  • Shared version formatter utilities for transforming data per version
  • Header-based versioning with middleware version extraction
  • Content negotiation versioning (Accept header parsing)
  • Deprecation handling with Sunset headers and successor-version links
  • Versioned handler factory for dispatching to version-specific logic
  • Per-version OpenAPI documentation generation

Usage#

Via CLI#

Loading code block...

Via AI Assistant#

Ask your AI assistant:

  • "Use the API versioning pattern from Bootspring"
  • "Apply the Bootspring API versioning pattern to my project"

Key Considerations#

  • Plan for versioning from the start, even if you only have v1
  • Use URL-based versioning for public APIs (most explicit) and header-based for internal APIs (cleaner URLs)
  • Deprecate gracefully by communicating sunset dates and giving clients migration time
  • Support at least two active versions simultaneously during transitions
  • Document differences clearly between versions so clients know what changed
  • Monitor version usage to understand when it is safe to retire old versions

Related Patterns#