Versioning Protocols

Header-Based Versioning

Header-based versioning passes the API version in a custom HTTP request header (e.g., API-Version: 2026-04-01 or Accept: application/vnd.api.v2+json), keeping URLs clean and enabling more granular version control. Aligns well with full SemVer strings and content negotiation patterns.

GitHub

Documentation

📖
Documentation
https://redocly.com/blog/api-versioning-best-practices

API entry from apis.yml

apis.yml Raw ↑ 
aid: versioning-protocols:header-versioning
name: Header-Based Versioning
description: 'Header-based versioning passes the API version in a custom HTTP request header (e.g., API-Version:
  2026-04-01 or Accept: application/vnd.api.v2+json), keeping URLs clean and enabling more granular version
  control. Aligns well with full SemVer strings and content negotiation patterns.'
humanURL: https://redocly.com/blog/api-versioning-best-practices
tags:
- Header Versioning
- Content Negotiation
- REST
- API Design
properties:
- type: Documentation
  url: https://redocly.com/blog/api-versioning-best-practices