API Bites — Versioning APIs

Versioning Managed APIs

TRGoodwill

Published in

API Central

6 min readSep 1, 2022

API Versioning Schemes

A key aim of business resource APIs is stability. However, in the pursuit of continuous improvement, breaking changes are almost inevitable, and in order to avoid a ‘big-bang’ coordinated cut-over there will occasionally be a need to support more than one version of an API. The most common schemes to manage multiple versions of an API are parameter or HTTP header driven, API management controlled or versioned URLs.

Parameter or HTTP header driven (agreed convention)

In a specification-first enterprise managed API capability context, a parameter or HTTP header driven version management scheme is unworkable. It is impossible to clearly document, relying on static text or back-channel communication, and is complex to mediate. OpenAPI operations just aren't defined that way — the URI path, method and media type uniquely identify an interface contract.

Overloaded Content-Type and Accept header (versioned media type)

Under this scheme, the API description document might describe one or more representations, each keyed to a unique, versioned content media type. It is then possible for a client to use overloaded Content-Type and Accept headers to send or request a specific version of a payload. e.g. Accept: application/json; version=2

This approach may suit a technically adept small enterprise with control of both API providers and clients, but it is not a good idea for a large organization or one with a large number of external clients for various reasons:

Loss of clarity : It is a non-standard approach that client portals will not clearly explain — an explanation must be embedded in API description fields. Multiple schemas and versions across multiple operations make the specification more difficult to understand and validate.
Client management is difficult : It is not possible to deprecate an older version (disallow new clients), and in-built API management tools to identify and notify users of retiring API versions won’t help— client data will need to be harvested from analytics for manual notification.
Not standards compliant: The approach does not align with the OpenAPI 3 specification, which asserts that “the media types listed below the content field should be compliant with RFC 6838.”

API management controlled (active subscription)

API management controlled version routing is a compelling idea — the client is routed to the version of the API to which they are subscribed via an un-versioned resource URL. There are some points to consider:

At this point in time, the approach is not widely supported, will be implemented inconsistently, and will limit platform options.
Questions about the mechanism worth asking; How easily can a client back-out their cut-over to a new version when previous versions are deprecated? How and when is the client cut-over when subscriptions must be authorised by the API owner?

If these challenges prove navigable, this may be a good option. Some clients will not need to update code between versions, and the management of HATEOAS links becomes simpler and more flexible.

Versioned URLs (explicitly addressed)

Versioned URLs are widely employed for the management of API versions. The scheme is somewhat limiting but uncomplicated, making it easy for clients to comprehend and control which API versions they interact with. This is the default API versioning mechanism in a specification-first managed API environment, and this bite-sized discussion makes the (low-risk) assumption that this scheme will be employed.

Versioned URLs must only include the MAJOR version as part of the URI, in the format ‘v{MAJOR}’, e.g.

/membership/v1/applicants

The version number typically precedes the resource (and API specification) name in the path — it should never appear between the resource name and the resource ID.

Minor and patch versions (assuming SemVer versioning) must NOT be included in the URI as such changes are by definition backwards-compatible.

Semantic Versioning

Unless there is a compelling reason not to, API Models and specifications should be managed with semantic versioning.

{MAJOR}.{MINOR}.{PATCH}

The first version of an API must always start with a MAJOR version of 1.

Versioning should align across the domain and REST models, and the API specification. Ideally, domain modelling tooling would manage semantic versioning across derivative artifacts, including API specifications. As a guide the following rules should apply when incrementing the API version number:

MAJOR version when incompatible or breaking API changes are made,
MINOR version when functionality is added in a backwards-compatible manner, and
PATCH version when backwards-compatible bug fixes are made.

Backwards Compatibility

Backwards compatible changes include:

Addition of a new field (non-mandatory) to a representation
Addition of a new operation
Addition or removal of HATEOAS links
Additional support of a new media type (e.g. Accept: application/pdf)

The following changes are NOT considered backwards compatible:

Removal of fields from representations
Changes of field data types (e.g. string to boolean)
Removal of an operation
Removal of media type support
New or tightened API security definitions

Test Environment Break-Fixes

Major version increments should apply only to breaking changes to APIs deployed to production, and this can create difficulties when deploying break-fixes to yet-unpromoted APIs in integrated test environments. In this case increment the minor version number and use API analytics to identify and notify active API consumers that are likely to be impacted.

Replacing a Major API Version

Justify, Document and Socialise. Introducing a new major API version will impact all consumers. Before deciding to introduce a new major version, API owners should explore all possible alternatives. A decision to introduce a new major version should be documented as an Architecture Decision and API owners should ensure that the potential impacts are discussed in agile planning forums.

Decouple Cut-over. The newly deployed version is effectively a new API, and consumers must subscribe to the new API version in order to use it. With each new major version of the API the older versions should be deprecated (no new subscribers) and maintained until all consumers have cut over to the new version. This can add introduce significant complexity on the development and support side.

Communicate a Retirement Schedule. Use API Management metrics to identify consumers and communicate an API deprecation and retirement schedule with sufficient notification. API deprecation and client notification are supported by most API management platforms.

Documentation and Automation

The OpenAPI “info” object “version” field must be contain the full semantic version number of the API , e.g. version: 2.3.1 . OpenAPI document linting should ensure that version numbers and versioned URLs align.

Managing API lifecycles with model driven development, API generation and automation is discussed in Managing API Lifecycles with Model Driven, Integrated DevOps

Versioned URLs — Interoperability Considerations

HATEOAS

There are limitations concerning the utility of fully qualified, cross-resource HATEOAS links when APIs are managed and URLs are versioned. There may be circumstances in which an HATEOAS link may not reflect the version of an API to which a client is subscribed, resulting in an invalid link. HATEOAS links constrained to operations that occupy the same versioned namespace as the parent resource are safe in this respect.

Business Events

If enterprise business services are expected to publish both business resource APIs and business events, a versioning strategy for APIs will almost certainly impact business event models and management.

When event messages are aligned with the REST representation of a business resource (per W3C Websub protocol or sibling AsyncAPI schemas), a major API version update will result in a change to the event schema. In order to avoid a requirement for a coupled ‘big-bang’ cut-over of all subscribers to a new version, versioned event topics and multiple versions of event schemas will need to be supported.

Topic and event schema versioning does not apply to ‘light-ping’ business event messages, which return only a notification that the state of a resource has changed. A light-ping message might however contain an array of multiple versioned resource URL links to which the event applies. Subscribers would be expected to retrieve the current state of the resource via the versioned API for which they are registered. E.g.

"resourceURLs": [
       "/membership/v1/subscriptions/12B34C",
       "/membership/v2/subscriptions/12B34C"
]

Wrap-up

Versioning enterprise managed APIs can have far-reaching consequences, for intelligibility and self-service, the degree of client coupling, for HATEOAS, and for event management. The versioning strategy should be carefully considered in consultation with stakeholders, documented in an Architecture Decision Register, and clearly articulated in API design standards.