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.
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.
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
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.
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.
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.
- 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.
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.
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.
- 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.
- 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.
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.
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.