How to effectively communicate API changes via automation

Whether Experience, Process, or System APIs, application programming interfaces are the fabric for creating apps. APIs enable organizations the flexibility to achieve their business, technical and organizational objectives.

Communicating and automating the API notification process to inform stakeholders that a new API exists or has changed allows stakeholders to capitalize on new opportunities so they can focus on creating new processes or generating new revenue streams. Plus, automation limits the risk of human error, saves time on executing repetitive tasks, and allows team members to focus on other activities.

Using automation to communicate API changes

MuleSoft’s Connectivity Benchmark Report found that 90% of organizations have a clear integration and API strategy, and over a quarter of respondents said leaders now demand that all projects abide by a company-wide API integration strategy.

With this perspective, how can we aid in the management, growth, and communication in the API ecosystem? Two solutions come to mind. First, we can use MuleSoft Universal API Manager to serve as the central source to manage and govern any type of API. The second which is crux of this article is how to effectively communicate API changes to stakeholders in the API ecosystem.

4 steps to communicate API changes

APIs are the fabric of application development. With continued innovation and improvements, new APIs will get created, depreciated, or changed. To effectively communicate these API changes, you need to follow and understand these four steps:

1. Know your API audience
2. Establish your communication channels
3. Identify the type of API change
4. Determine the notification message

1. Know your API audience

The key to communicating API changes is to know your audience. Your audience is the “Who” that may get affected by a new or changed API. This can range from internal organizational stakeholders such as developers, managers, and executives or API consumers.

API consumers may be business partners or platform innovators. Business partners may integrate their applications with your organization’s platforms. Innovators use APIs to create unique business opportunities to generate new revenue streams.

Knowing your API audience sets the foundation for communicating API changes. The audience is the point of contact to send notifications to when an API change occurs or the creation of a new API.

2. Establish your communication channel(s)

The communication channel notifies the audience that an API has changed or an addition occurred. The communication channel delivers fit-for-purpose API content (e.g. name, description, location). It also provides support for proactive and passive communication. Proactive notifications are when the API change impacts existing applications. API consumers will need to act on the event so their applications do not break. Passive notifications don’t need an immediate response and are more informational.

To achieve the communication channel objectives, there are three approaches to use. First, adopt a collaboration platform, second, use portal software, and third, write code. The three approaches enable audience notification and message delivery and API documentation access.

Collaboration platforms enable communication amongst audiences (e.g. developers, API consumers, managers). Collaboration platforms also allow audiences to work together. Slack is a good example of this. Slack facilitates real-time audience interactions and embeds automated workflow.

Portal software serves as a central platform for audiences to gather as a community and access information – in this case new or changed API details. Anypoint Community Manager provides this capability and serves as a portal for the API community members. It can also auto-populate API documentation from Anypoint Exchange.

Finally, code within your application can assist in communicating API changes. Developers can write warning headers in APIs or call a common service to check API status. Plus, sending email notifications informing of upcoming API change events can occur. Audience members will be informed that the API will change or get deprecated. Employing these approaches with automation will improve communication and enhance the audience experience.

3. Identify the type of API change

Several factors may exist for an API change to occur. New business capabilities, process changes, or architecture and design improvements cause API changes. These API changes can be categorized as breaking or non-breaking.

• Breaking changes are API modifications that cause an application to fail. They can wreak havoc on your environment. Some examples of API breaking changes are adding required query parameters, a data format change, or renaming an API resource.
• Non-breaking changes will not impact API consumers and are more informational. Non-breaking changes are adding a new operation, adding an optional data attribute, or an optional query parameter.

Providing immediate visibility to your audience when identifying API changes is key. This will enable the audience to react and respond to the change. It will reduce the risk when deploying the API. Additionally, it will instill trust in your audience. The audience knows there is a process in place informing them of changes and potential impacts on their applications.

4. Determine the notification message

Make the API notification message easy for the audience to understand. To do this, segment the audience and identify the needed content. The content needs to be necessary, pertinent, and useful. Meet with each audience type and get important specific requirements. Remember, delivering the right message at the right time is crucial. This will prevent information overload and avoid confusion. Your audience will know the delivered message is relevant.

Putting it all together

Now that you have a picture of the four defined steps to communicate API changes, let’s recap the technologies to use:

• Slack: Use Slack for collaboration, communication, and automating the audience workflow.
• MuleSoft Anypoint Community Manager: This should be your portal. You can build communities around your APIs and present API documentation to the audience.
• MuleSoft Anypoint Exchange: Anypoint Exchange contains a curated catalog of API and API-related information. The information from Exchange is auto-populated into Anypoint Community Manager. Embed warning messages within your APIs to inform the audience of changes.

Integrating and automating these products will provide a flexible solution to communicate API changes and put you on the path to cultivating trust with your audience and reducing the risk in the API ecosystem.