API versioning is a fundamental practice in software development that involves the creation and maintenance of distinct versions for an application programming interface (API). The primary objective is to safeguard the functionality of applications dependent on the API from disruptions caused by changes or updates.
This practice is paramount for preserving backward compatibility, ensuring that applications using older API versions remain functional. Meanwhile, it facilitates the seamless integration with newer clients, allowing them to leverage the enhanced features of the updated API.
However, API versioning is not just a technical concern; it has direct implications for the success and growth of your business. It helps you maintain developer satisfaction, support diverse user needs, innovate, and manage risks effectively. By providing a reliable and consistent experience for API consumers, you can build a loyal user base, foster a thriving ecosystem, and ultimately drive business growth and revenue.
Before we dive into how Traefik Hub improves API versioning, let’s first take a look at why it’s important for both API producers and consumers.
The Importance of API Versioning
For API Producers
In the fast-paced world of API development, the challenge lies in innovating with velocity while avoiding disruptive changes. For API producers, the absence of a common language among different teams discussing changes can result in a lack of context, leading to errors as interpretations vary. Accelerating the development process may intensify these errors, while slowing down compromises the speed of launching new features. In this regard, API versioning is a crucial solution to strike a balance between innovation and resilience.
For API Consumers
On the consumer side, API versioning addresses the challenges of keeping pace with releases and changes that can lead to integration issues and potential disruptions. With a well-defined versioning strategy, API consumers are more informed and can adapt to new releases at their own pace. This not only keeps existing users satisfied but also attracts new users who seek a reliable and future-proof API.
Ultimately, API versioning acts as a form of insurance for both producers and consumers. It mitigates business risks by providing a controlled mechanism for introducing changes, minimizing the chances of costly outages and revenue loss. Additionally, adhering to versioning practices helps ensure compliance with legal and regulatory requirements, safeguarding the business against potential legal challenges and associated penalties.
How Traefik Hub Solves API Versioning Challenges
Traefik Hub transforms the API versioning landscape by providing a unified solution that caters to both API producers and consumers. For API producers, Traefik Hub offers a common actionable language, streamlining the understanding, expression, and management of change through innovative approaches like CRDs—a.k.a., Custom Resource Definitions—and GitOps. This empowers developer teamwork at scale and speed while minimizing risks of breaking changes.
On the other side of the spectrum, Traefik Hub prioritizes the needs of API consumers by emphasizing ease of use and clarity. The platform introduces API Version CRDs coupled with internal semantic versioning and external flexible version matchers, offering consumers a straightforward way to comprehend and interact with APIs. This not only enhances the developer experience but also ensures that changes are clearly communicated and can be adopted without friction. Traefik Hub’s API Developer Portals expose all API versions clearly, promoting efficient information flow between API producers and consumers.
In order to facilitate efficient communication and collaboration, CRDs are used to standardize changes. This common language ensures that everyone involved understands the modifications, reducing the risk of errors and misinterpretations. As a result, teams can move faster without sacrificing the quality and stability of the API. This aligns with the need for speed without compromising accuracy, enabling a smoother development process.
API Versioning Your Way
We believe in letting developers seize control, making their own choices. We don't impose a rigid versioning structure; we empower you to define the version matchers that suit your unique needs—also ensuring that versioned and unversioned APIs can coexist harmoniously.
Traefik Hub offers four API versioning methods, giving you the freedom and flexibility to choose the best approach for your particular situation:
- Path-based (/v3): The traditional route for versioning, with a clear, user-friendly path to your API versions.
- Query-based (?v=3): A versatile option that embeds the version directly into the API request, simplifying integration.
- Media type-based (Accept/Content headers): This approach leverages headers, offering precise control over content negotiation and version selection.
- Header-based (any custom header): The ultimate in customization, letting you set up your own headers to manage API versions.
To provide the best possible product, we looked around on the market, and realized most other API management tools offer only a subset of these methods or even stick to just one, limiting you to follow the path they chose.
Mix and Match Versioning Methods
For Traefik Hub, it's not just about having multiple options. You can combine them in ways that make sense for your project. Traefik Hub provides the unique capability to mix and match these versioning methods with AND/OR relations, giving you the power to craft the perfect strategy to meet your specific needs.
Tired of using numbers for publishing versions? Use calendar dates, cheese names, or anything you like. We don’t limit you; it’s your API, it’s your API governance, and your versioning convention.
Structured Flexibility
Though the offered freedom is great, it shouldn’t sacrifice structure and maintainability. Traefik Hub uses semantic versioning internally to keep track of the version changes and to allow you to mark what is the current API version, what are the older ones, and what are future releases.
This flexibility in interacting with your APIs on the request level paired with the structured internal representation allows you, your team, and your clients to always stay on top of the API version proliferation.
And in case you want to expose an always up-to-date version or a fallback version, a catch-all route can be marked for a versioned API, which still allows unversioned access to the underlying service. It can be beneficial to test the latest functionality or to provide a fallback version to clients that access the API without any version matcher (i.e., access a version without explicitly specifying the version anywhere in the request).
Finally, Traefik Hub’s API and API Version CRDs allow you to seamlessly alter regular and security headers on both APIs and API versions. Add, remove, and manipulate request and response headers on a per-version basis to fortify your API infrastructure.
Use Case: Traefik Airlines
Let’s take a look at Traefik Hub’s API versioning capabilities in action. Traefik Airlines, our fictitious company, is a modern airline company that offers a variety of digital services to its customers and partners. To meet the evolving needs while maintaining business stability, Traefik Airlines must implement a robust API versioning strategy. Let's explore how this can be achieved by using Traefik Hub API management.
Traefik Airlines provides a RESTful API for customers to book flights and manage reservations. Customers can retrieve real-time flight information such as schedules, delays, and gate changes. The API offers mobile check-in, boarding pass retrieval, and gate information. Customers can also interact with an API that manages loyalty points and rewards.
Additionally, third-party travel agencies integrate with Traefik Airlines to offer flight booking services to their customers. They also need to maintain integration with airport systems for baggage handling, gate allocation, and passenger tracking. Collaboration with payment providers is with the utmost importance to process transactions securely.
As we can see, there are many clients, many APIs and many developers supporting the company’s digital infrastructure. The demanding environment screams for using API versioning to satisfy all needs, provide business continuity and let the airline expand at the same time, deploying new API releases on a regular basis.
Flexible API Versioning with CRDs
Let’s say, for example, that Traefik Airlines has already deployed Traefik Hub to their Kubernetes clusters running their microservices, and they are now ready to define APIs and API versions.
Let’s pick the Customer API as an example.
---
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: customer-api
namespace: apps
labels:
area: customers
module: crm
spec:
pathPrefix: "/customers"
currentVersion: customer-api-version-one
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIVersion
metadata:
name: customer-api-version-one
namespace: apps
spec:
apiName: customer-api
release: 1.0.0
title: "v1 with URI path"
routes:
- pathPrefix: /v1
stripPathPrefix: true
service:
name: customer-app-v1
port:
number: 3000
openApiSpec:
path: /openapi.yaml
port:
number: 3000
Here they define the first version of the Customer API.
The API CRD is labeled for later reference in an API developer portal providing documentation, API access policies to allow users API consumption, API gateways to publish it to the defined audience, API collections to create virtual API groups, or API rate limit policies to secure the backends from rouge clients or malicious actors. The CRD also defines a path prefix for the whole API containing all versions, and references the current version.
The API Version CRD defines the first version of the API, internally versioned as 1.0.0 and exposed as /customers/v1 in the URI path, from which the version is stripped when passing the request to the microservice exposing the API. Here, they could have used any text, date, or even a cheese name to publish the API. If they completely omitted the routes block, the version would have become a catch-all route, accepting any unversioned traffic. The service also exposes an OpenAPI specification which will be attached to the API version on the developer portal.
Let’s say they would have opted for another API versioning method. How could they implement it with the provided flexibility but still maintaining a clear structure?
routes:
- queryParams:
my-version-param: "1"
In this case the API version is exposed at /customers?my-version-param=1. Need to expose a version for another language, but the two should be applied at the same time?
routes:
- queryParams:
my-version-param: "1"
lang: "hu"
Now the version is available at /customers?my-version-param=1&lang=hu. Add as many parameters with any value as you like.
Need to expose the same version with different methods? We’ve got you:
routes:
- queryParams:
v: "1"
lang: "hu"
- headers:
v: "1"
lang: "hu"
- headers:
Content: "application/vnd.example.v1+json"
lang: "hu"
- pathPrefix: /v1
queryParams:
lang: "hu"
Now the version is available at the following ways:
- Using query params at
/customers?v=1&lang=hu - Using the custom headers
v: 1andlang: huat/customers - Using media-type type versioning with extending the standard content negotiating header
Content: "application/vnd.example.v1+json"and a customlang: "hu"at/customers - Using the path prefix and a query parameter at
/customers/v1?lang=hu
You can mix and match all these route options in an API version, both the CRD and the web user interface displays it in a structured, easy-to-digest manner.
In case Traefik Airlines need to publish the 2nd version of the API, they deploy the new supporting service with the corresponding new OpenAPI specification, reference it in a new API Version CRD, and update the current version in the API CRD. And that’s it, the new version is published. The main changes to the first version are emphasized below:
---
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: customer-api
namespace: apps
labels:
area: customers
module: crm
spec:
pathPrefix: "/customers"
currentVersion: **customer-api-version-two**
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIVersion
metadata:
name: customer-api-version-two
namespace: apps
spec:
apiName: customer-api
release: **2.0.0**
title: **"v2 with URI path"**
routes:
- pathPrefix: **/v2**
stripPathPrefix: true
service:
name: **customer-app-v2**
port:
number: 3000
openApiSpec:
path: /openapi.yaml
port:
number: 3000
None of the configuration building on top of the API needs to be altered, the API access policies, rate limits, collections, etc. stay the same. Publishing the new version is propagated to the API gateway and the portal transparently. Now clients have a backward-compatible way to adapt to the new version without any service disruption to the existing consumer configuration.
You can find even more information about API versioning in our documentation.
Wrapping It Up
In today's fast-paced software development landscape, API versioning is not just a technical necessity but a strategic imperative for a thriving and sustainable API ecosystem. As software development velocity accelerates, API versions provide stability, ensuring existing integrations remain intact with backward compatibility. While you evolve and improve your APIs, it gives your consumers a predictable environment to adopt innovations at their own pace.
Traefik Hub API management simplifies transitions, minimizes disruptions, and offers a smooth migration path for legacy APIs by extending rather than replacing non-versioned APIs, allowing coexistence. With this internal semantic versioning system and flexibility in versioning methodology, Traefik Hub accommodates diverse client needs and enhances the overall experience for both developers and clients.
This is a companion discussion topic for the original entry at https://traefik.io/blog/api-versioning-with-traefik-hub