API Transit Basics: Communication

This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through.

Moving further towards the human side of this API transit journey, I’d like to focus on one of the areas that I see cause the failure and stagnation of many API operations–basic communications. A lack of communication, and one way communication are the most common contributors to APIs not reaching their intended audience, and establishing much needed feedback loops that contribute to the API road map. This portion of the journey is not rocket science, it just take stepping back from the tech for a moment and thinking about the humans involved.

When you look at Twitter, Twilio, Slack, Amazon, SalesForce, and the other leading API pioneers you see a handful of communication building blocks present across all of them. These are just a few of the communication elements that should be present in both internal, as well as external or publicly available API operations.

  • Blogs - Make blogs a default part of ALL portals, whether partner, public, or internal. They don’t have to be grand storytelling vehicles, but can be used as part of communicating around updates within teams, groups, and for projects.
  • Twitter - Not required for internally focused APIs, but definitely essential if you are running a publicly available API.
  • Github - Github enables all types of communication around repos, issues, wikis, and other aspects of managing code, definitions, and content on the social coding platform.
  • Slack - Leverage Slack for communicating around APIs throughout their life cycle, providing a history of what has occurred from start to finish.
  • API Path IDs - Establish common DNS + API path identifiers for creating threads around each API, allowing for discussions on BitBucket, Slack, and in emails when it comes to each API.

I recommend making communication a default requirement for all API owners, stewards, and evangelist who work internally, as well as externally. Ensuring that there is communication around the existence, and life cycle of an API, and helping make sure there is awareness across teams, as well as up the management chain. It’s not rocket science, but it is essential to doing business around programmatic interfaces. You don’t have to be a poet, or prolific blogger, but you do have to care about keeping your API consumers informed.

Communication around API operations is easily overlooked, and difficult to recreate down the road. Just put it in place from the beginning, and don’t worry about activity levels. Be genuine in what you publish and share, and be responsive and open with your readers. Whenever possible make things a two-way street, allowing readers to share their thoughts. Track everything, and route it back into your road map, leveraging all communications as part of the API feedback loop.