Communicating changes to APIs and the operations around them is essential to the delivery of reliable, useful, and secure digital API resources and capabilities. Change is an inevitable aspect of API operations, even with seemingly stable and mature APIs. Communication across teams producing APIs, as well as with consumers who integrate APIs into their applications, is the foundation of managing API change.
The communication surrounding change can be made self-service via road maps and change logs, stamped on API contracts using modified dates, and baked into our APIs with versioning. It can also be made real-time via email, newsletters, and the channels API producers and consumers are using. Communication needs to be part of every change to an API no matter how seemingly minor it might be.
Communicating changes is often times more theater than not, but it goes a long way to help soothe API consumers, and build trust over time. Communicating with each change establishes a kind of heartbeat with consumers that can help keep API producers and consumers in alignment with each release, increasing the velocity over time due to closer alignment.