Skip to content

How to handle an API breaking change

How to handle an API breaking change?

A breaking change for an API is any change to the API contract which will require the client applications to update the implementation on their side if they want to use the updated API.

Sometimes you will also hear people describing those changes as backwards incompatible updates.

A breaking change can be as small as a new mandatory field or as big as existing resources and data types being renamed/removed or replaced by new ones.

In these cases, the major version of the application should be incremented and that would cause the version id of the Mule API to be incremented as well.

Overview

Let’s see what steps we should take to deliver a breaking change for a Mule API.

Steps we should take to deliver a breaking change for a Mule API

We start from the Design Centre where we will need to update the contract, then we publish the updated asset to Exchange and document it, we create a new managed instance of the API in API Manager and finally, we import the new version of the API contract in Anypoint Studio and we update the API Implementation.

Design Center

Before we start updating the API contract in Design Center we should have a good idea if the changes will make the API backwards incompatible or not. If we know that from the beginning, then it would be a good idea to create a new branch of the API Contract and do all the changes in the new branch.

  • Branch the API contract

For new changes made to API contract, especially if they are backwards incompatible, ensure that a ‘branch’ has been created so that it can be easily identified in Design Center.

Graphical user interface, application, email

Description automatically generated
API contract

At this stage, we should follow the MuleSoft specification phase-cycle where we might need to do several cycles of design, Simulation, Feedback and Validation before we publish the API to Exchange as a Stable Asset.

Once all stages of the specification phase have been completed, we publish the API updates to Exchange as a Stable Asset with a new major version.

  • Publish contract updates to Exchange as a Stable Asset with a new major version
Graphical user interface, application

Description automatically generated
Publishing of API updates

At this moment it is important to increment the major Asset Version number in which this change will be published (e.g. 2.0.0). Also make sure the API Version (e.g., v1, v2 etc) is in line with the Asset Version.

Graphical user interface, text, application

Description automatically generated
Breaking change API

Exchange

  • Document the Asset in Exchange

When a new major version of the API is published to Exchange, Exchange interprets the major version change as an opportunity to re-document the asset. The API designer can use this opportunity to document the API as a completely new Exchange asset or as an extension of the previous major version.

A potential consumer can switch between major versions using the dropdown to the right of the API name.

Graphical user interface, text, application, email

Description automatically generated
Exchange

API Manager

  • Create a new managed instance

Since the API has a new major version, a new managed instance of the API should also be created in API Manager. Ensure that the correct API and Asset version fields are configured for the new major version.

Graphical user interface, application

Description automatically generated
API Manager
  • Write down the new Autodiscovery id

After creation, write down the new Autodiscovery id because it is necessary to update that before deploying the version of the API Implementation.

Graphical user interface, text, application

Description automatically generated
Autodiscovery id

Anypoint Studio

  • Import the latest API contract from Exchange

To implement the changes made to the API contract, fetch the latest version of the API contract from Exchange. This can be done by right-clicking on RAML Dependency and selecting Update Version.

Graphical user interface, application, Word

Description automatically generated
API contract

This step will fetch the update RAML file as a maven dependency well as any other dependent RAML fragments.

Then it’s important to generate again the flows so that the APIkit Router Configuration has the correct version.

Graphical user interface, text, application

Description automatically generated
Breaking change API
  • Implement changes

Ensure that the API implementation supports the changes made to the API contract. Since this is a major version change, the API’s endpoint URL must be updated. This can be done directly in the HTTP Connector properties or in a separate properties file.

  • Update the Autodiscovery id

Due to the creation of a new API version in API Manager, the Autodiscovery configuration properties will need to be updated. Use the Autodiscovery id captured in one of the previous steps and update it directly in the Autodiscovery Configuration or in a separate properties file.

Graphical user interface, text, application, email

Description automatically generated
API Autodiscovery
  • Deploy the new version of the API

Once the implementation is complete, deploy the updated application to Runtime Manager. The deployment can be done either through Anypoint Studio (see image below), the Mule Plugin for Maven, or through the Runtime Manager APIs. 

Graphical user interface, text, application

Description automatically generated
Anypoint Studio

Once deployment is complete, check in API Manager to ensure that the new version of the API has registered successfully with API Manager using the new autodiscovery id.

Graphical user interface, application, website

Description automatically generated
API Manager

Good Practises

Consider using the following good practices:

  • Use the version id in the name of the API during deployment time. For example, this API would be deployed as breaking-change-api-v2
  • Don’t maintain more than 2 major versions of the same API, if a new breaking change is coming consider deprecating the oldest version.
  • After deprecating an API allow a time of around 3 months so that the client application using that version can move to the newest version before decommissioning the deprecated API version.

Read our other articles about MuleSoft.