API Academy

Sponsored by Layer7

Two people sitting at a desk with computers.

Three Questions for API Change Management

By Adam DuVanderPosted on

As you build and add more features to your API, it will become imperative to consider how your teams make changes to the project. When multiple engineers are adding a new feature to an API they need to cooperate to ensure consistency and avoid breaking the app. 

Change management allows us to create a process or a set of rules that shapes the way the API grows as more endpoints are added and as existing functionality changes. Consider the following three factors whenever making changes to an existing API:

  • Will your API be backward compatible? When making changes to an API, consider whether it’s backwards compatible for existing users. One strategy is to use versioning. Assuming we’re making changes to an API that’s on v2, instead of deploying changes to that same v2, create a new version as v2.1 while retaining v2. This allows different clients to use different versions of the API depending on their implementation. Instead of forcing issues, bugs or breaking changes, we allow delivery of the previous versions to continue. That way, both the previous and current versions work as expected for the customers that are using them. Naturally, documentation should also be available for each version in operation and should any key differences. You can also go beyond incremental versioning and use change management rules that specify which kinds of changes should result in a new API version vs which changes can be made without a whole new version. It’s wise to constrain how many versions you deploy to be the minimum necessary. Avoid breaking changes but strive for simplicity.
  • Are you adhering to API Specification Formats? The advantages of proper API governance are much clearer when the project gets bigger with several moving parts. Good governance entails having specifications for all API endpoints to ensure consistency. Each endpoint should be structured similarly,  so API endpoints’ headers, body, response, etc will be the same format. Example specification formats to follow include the OpenAPI specification and the GraphQL specification. With a specification, whoever is joining the team and wants to make these changes needs to follow the appropriate specification to keep the APIs consistent.
  • Do you have observability? Good API change management will incorporate the ability to anticipate the effects of changes and then monitor them in production. Observability means understanding everything about the API system so that all the internal components can be inspected and predicted. This also includes traditional monitoring and writing tests to ensure that the API always functions as it should. Analytics and reporting tools enable you and your teams to observe  the details and general overview on the performance of the API at any time. This way we can easily detect the effect of changes we’ve made, or plan to make, to our API.

These three factors should be kept in mind when making changes to APIs as you develop them over time. With thoughtful change management processes in place for your engineers to follow when updating APIs, you can continue to deliver your services uninterrupted while still allowing improvements and restructuring.