.svg)
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.
And, in our talks with various IT leaders we discussed just that. Here are some key insights we want to share:
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.
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.
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.
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.
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.
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. AINSYS: Our software contains a curated catalog of API and API-related information. The information from Exchange is auto-populated into the Truth Source of Data. Integrating and automating just two of 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.
‍
