Skip to content

API versioning

This page explains API versioning.

Introduction

Traefik Hub empowers comprehensive API version life-cycle management, offering the capability to define distinct configurations for various API versions.

What is API versioning?

API versioning is the practice of creating and managing multiple versions of an Application Programming Interface (API) to handle changes, updates, and improvements over time while maintaining backward compatibility and supporting existing clients.

There are various strategies for implementing API versioning, such as URI path versioning, query versioning, header versioning, or using custom media types.

The choice of strategy depends on the specific requirements of the API and the preferences of the development team.

Regardless of the approach, API versioning is a critical practice for managing the lifecycle of an API and ensuring a smooth and stable experience for both API providers and consumers.

Version strategies supported by Traefik Hub

URI path

In the URI path strategy, the version number in the path of the URI. This is often used together with the prefix v.

curl https://api.example.com/flights/v1
curl https://api.example.com/flights/v2

Query parameter

This type of versioning adds a query param (parameter) to the request that indicates the version.

curl https://api.example.com/flights?version=1
curl https://api.example.com/flights?version=2
curl https://api.example.com/flights?version=1&lang=fr
curl https://api.example.com/flights?version=2&lang=fr

In this method, you use a custom header in the request. This leaves the URI of your resources unchanged.

curl -H "Version: 1" https://api.example.com/flights
curl -H "Version: 2" https://api.example.com/flights

Media type

Media type versioning, also known as "content negotiation versioning", is the practice of specifying the protocol version via the Content-Type HTTP header.

curl -H "Content: application/vnd.example.v1+json" https://api.example.com/flights
curl -H "Content: application/vnd.example+json;version=1.0" https://api.example.com/flights
curl -H "Accept: application/vnd.example.v1+json" https://api.example.com/flights
curl -H "Accept: application/vnd.example+json;version=1.0" https://api.example.com/flights

What's next