The API industry thrives on change. As the needs of the consumer grows, so too do the demands on the API provider. Accordingly, providers are faced with the growing prospect of constant technological evolution.

While this cycle of change is largely a positive one, it does bring with it some unique challenges; one such challenge is that of communicating change to your developer users. Whether it be versioning, endpoint retirement, or other changes, developer users in the modern API landscape expect an allocated time frame, and a much more nuanced, fully-addressed method of communication.

Today, we’re going to look at some of these methods of communication, and identify why traditional passive communication approaches, such as those used in traditional API versioning, do not adequately provide an answer to the issue at hand. We’ll discuss 6 strong ways to communicate API change, as well as highlight some caveats in different communication modes.

Why Passive Communication is a Problem

APIs communicate passively when they post changes without attempting a planned public notice; an organization creates the information and puts it in a static location, expecting users who care to stumble across it.

This is ineffective for a variety of reasons. While versioning is not in itself a death knell for the API, without a communication plan in place it can create more problems than it solves. It can result in users finding their firmware, software, and other elements to be incompatible with a previously configured endpoint or resource. In other words, passive communication as a sole method of change management can easily result in breaking change and unhappy clients.

Proper notification can address this, of course, giving users ample time to ensure configuration, but the client-side burden is more complex than you may think. The process of verifying the version, updating credentials, and integrating with the new changes can result in significant time dedication. The more passive communication used to address these changes, the greater importance is placed on the user. Ultimately, this is an inappropriate shifting of responsibility.

What can we do, then, to make the communication of these changes better, more effective, and ultimately an improvement on the basic, core nature of version-based passive change communication?

Defining the API Consumer

One of the best things we can do when communicating change is to identify who the user is for each of our services, and adopt a communication method according to their needs.

We can think of APIs as having three classes of users. A normal user is simply the most basic user using the most basic functions. Above this, super users require specialty functions and more complex services. Finally, internal users utilize the API from an internal point of view, either as part of the development team or as a business partner utilizing such internal endpoints.

Once we define the user, we could point them to specific aspects of change that are catered to the microservices they consume — this can avoid notification overload. In addition to function-specific alerts, learning about API consumer habits can also dictate what channels to privilege in your communication announcements.

For instance, if the average basic user utilizes Twitter to engage with the development team, proper change communication could be as simple as issuing a brief summary via a Tweet to such users. On the other hand, if none of your super users or internal users ever utilize Twitter, but instead prefer to use email, then such communication should occur via that channel.

6 Strong Ways To Communicate API Change

Now that we’ve set up some initial guidelines for communicating changes, let’s look at some specific communication methods. Not all of these methods are going to be appropriate for every use case – as such, it’s imperative that the developer must look at their user base and identify the specific best options for their given and limited needs.

Changelogs

One common method of change communication is a changelog. In essence, a changelog simply serves as a long-term tracking method of comparison between multiple versions. When an API updates, each change is noted as a deviation from the previous version, and this serves as a method of communicating not only what was changed, but why it was changed.

To make truly effective changelogs, however, you need to add a few elements to the traditional text-heavy solution. One key addition is links to previous changelogs in historical order, allowing users to work backwards and contextualize.

A changelog should be considered a method of communication, but one important element is to consider the method by which this changelog is issued. Active changelogs are almost always the best option, actively sent to users who utilize the given services. Passive changelogs, on the other hand, are fundamentally no different from the passive versioning communication approach discussed above.

Social Media

One excellent modern method of communication is through the use of social media. Sending out alerts for changes, and even using social media to respond to user needs, complaints, and questions about changes can be very effective.

That being said, such change notification should occupy its own developer account, so that this information doesn’t get lost in the rest of your social correspondence. This is especially important when API providers operate across multiple fields and functions, such as when a business consultant may provide an API for a secondary business purpose. In those cases, such separation is imperative.

However, if that’s not possible, at the least, each respective social media post should also be provided in news update form on a single webpage, so as to allow for linking from one notification to another. Ultimately, social media can be a very powerful tool, as long as it’s carefully considered and curated.

Automated Emailing

Using automated email services can effectively communicate change by providing ample space for notification and description of changes. That being said, emailing can be more complicated than other options due to the nature of emailing itself. Changelogs and social media are fundamentally opt in, meaning the user chooses to engage in such communication. Email, however, can occur without the user ever choosing to receive such information.

Accordingly, do not assume every user will want an update, especially if changes occur daily. Failing to address this would result in the very notification fatigue that we’re trying to avoid. Allow for subscription and notification settings. Additionally, provide an adequate method of opting out of such emails to ensure compliance with communication best practices.

Developer Portals and Visual Notification

One great method of communicating change is to use developer-centric tools. Something as simple as a dev log, a blog of sorts documenting development and choices made throughout the lifecycle, can be extremely effective. Part and parcel to this type of communication is the use of a development portal that utilizes some sort of representation of development progress to communicate change.

Mailchimp is a great example of this type of communication. Their methodology uses a red bar that fills as development is completed, and provides links to changes as they come. This type of development portal is great for contextualizing change and development over time, as well as the effect of each change on the entire system.

Mailchimp highlights API changes on the top of their dev portal pages.

That being said, this should not be used as a primary system, as it’s basically just a prettier version of a static, passive changelog that users can see by navigating to a site.

HyperMedia

A properly designed RESTful API can itself serve a sort of function of notification as well. Hypermedia has been said to be a prerequisite of a truly RESTful API – it’s lucky, then, that Hypermedia is a prerequisite to effective change communication in that realm as well.

With a proper Hypermedia setup, an object can be passed to the user that not only notifies said user of a change, but also provides a hypertext link to the changelog, to social media accounts, even to the new endpoint documentation. Hypermedia serves as a notification to the user for both version and the changes in that version, and multiplies the efforts to document change to greater levels.

Canary Release

In some cases, the differences between each change may not be stark enough to warrant communication in the methods previously discussed. Canary Release is one such example. In this approach, versioning is avoided by gradually exposing users to the new build over time, presenting a simpler, cleaner, and smoother transition for the users in question. Unfortunately, this also means that version notification is required, but such notification may not actually be appropriate for all users.

In these cases, such notifications should serve as a secondary service, rather than as a warning of interrupted service, new functionality, etc. – the transition should be completely seamless. The user should be aware of the possibility of a new version, but such a shift should not in itself require viewing the changelog.

Final Thoughts

While it’s tempting to stick to the tried and true, there are so many more modern and effective methods than simply issuing a plain version number or notification via the first contact with an API.

As part of this modern approach, it should also be noted that a single methodology is not always the best choice either. With a modern set of choices and a variety of channels to communicate change, a combination can be leveraged to coordinate updates to many user groups with customized communication content appropriate for each avenue and user group utilizing that avenue.

Ultimately, how one chooses to notify users of a change can be highly variable. What really matters isn’t so much the specific minutia of how you notify, but that you notify in a useful and appropriate manner given your specific use case, your user base, and the caveats that each unique situation represents. Proper notification is extremely important, and can make the difference in user experience that drastically changes the user flow and the perception of your API.

How is your platform getting the word out regarding API change? Let us know in the comments below.