Solution Patterns: API versioning with 3scale API management

In this Solution Pattern we will discuss how Globex, a fictitious retail company, evolves to handle new versions of an API across all layers: backend, API management platform, API consumers.

Contributors: Jaya Christina Baskaran (Red Hat)

Solutions Patterns help you understand the art of the possible with Red Hat’s portfolio, and not intended to be used as is for production environments. You are welcome to use any part of this solution pattern for your own workloads.

1. Use cases

Here are a few usecases where API versioning is undertaken by organisations

  • New features that impact existing specifications

  • Changes in business models such as new channels of collaboration

  • Change in payload format due to compliance or security reasons

  • Changes due to downstream integrations

  • Usecase deprecation or sunsetting

2. The story behind this solution pattern

In this Solution Pattern we will discuss how Globex, a fictitious retail company, evolves to handle new versions of an API across all layers: backend, API management platform, API consumers.

This solution pattern extend the Globex’s retail website whose existing OrderPlacement API is undergoing changes to

  1. Include an optional Delivery Instructions to make customer deliveries easier.

  2. Moving from First and Last names to a single Full name field to represent different cultures and conventions

3. The Solution

With the evolution of the enterprise and technology landscape, changes to the APIs become inevitable. A typical API goes through a lifecycle that starts with the conceptualization of an API and progresses through various stages, including design, implementation, testing, deployment, and ongoing management.

story

Changes in the API specification or the contract will have far reaching impact on across teams, organisations, community, partners touching upon a number layers including backend services, API management platform, API consumers. Each of these will need to be managed so that the system as a whole doesn’t break.

Some parameters to consider include

  • When to version, what to version and how to version

  • Who the are players in the API game

  • Transition on adoption of the new version

  • API retirement and sunsetting

We’ll apply all that we discussed above in this setting and see how Red Hat OpenShift and Red Hat Application Foundations, which includes 3scale API Management supports all of these critical aspects of API changes and versioning.