There is a reason why I encourage API providers to look at not just the technology of APIs but also invest heavily into the business and politics of API operations. There is a reason I evangelize a more open, web-based approach to doing APIs, even if you are peddling hardware and device APIs. It is because there are a number of human-centered elements present when doing APIs, that will define your services, and ultimately contribute to whether or not they are a success or a failure.
One example of this from my API news curation archives is from the Sonos API ecosystem, and a pretty big blunder in communication the audio device platform made late last year, that is significantly impacting their partnerships in 2017. Directly from the CEPro article:
A collective cheer roared from home-technology installers at CEDIA Expo 2016, when Sonos announced an API for home-automation integration starting with Control4 (Nasdaq: CTRL), Crestron, iPort, Lutron and Savant.
These partners – and most other respectable smart-home systems providers – have integrated with Sonos for many years, albeit with unsanctioned drivers created through reverse-engineering of a fairly straightforward UPnP-based protocol.
But the new API kind of snuck up on dealers and vendors alike, with their customers waking up to a brand new Sonos experience in late December, courtesy of an auto-update by Sonos.
The new experience was inferior to the original, with users unable to access Spotify or Amazon Music from the home automation system, except to select favorites created through Sonos’s own app.
When you are operating an API that many different businesses depend on, communication is essential. this is why I advocate that API providers always have a clear communication and support strategy, as well as the road map, issue management, and change log processes. Every single change has to be considered for its impact on the community, and you have to have a plan for how you will be communicating and supporting your API consumers needs around a change.
This is also why API providers should be understanding the benefits of hypermedia when it comes to change management. Hypermedia design patterns provide you with a more honest approach to dealing change, one that helps make your partner's clients more fault tolerant. It is well worth the time learning about the handful of leading hypermedia media types. Any one of them would have helped Sonos manage change.
There are multiple tools in the API toolbox to help you manage change. In the en,d the most effective tools involve human to human interaction, and actually talking to your partners early on about change, and making sure you have a robust communication strategy throughout your API lifecycle. Us engineers like to think it is the API technology making the magic happen, but in the end, there is more to this than just having application programming interfaces, it is about also having the right human interfaces.