This is my online domain where I work to understand the world of the Application Programming Interfaces, also known as APIs. This new way of sharing data using the web is touching almost every aspect of our increasingly digital lives, providing access to the bits and bytes that make our personal and professional worlds go round.

This is my research specifically into how API providers are managing their change log and communicating it to their API community. Many successful providers publicly share a complete change log of everything that has been done to a platform, being transparent with the community about what has happened.

API Evangelist is a network of data driven projects and APIs which I curate and manage as part of this ongoing research, hoping to provide easy access to the moving parts of my work. Everything you see here runs on Github, making everything forkable, and reusable for both humans and machines.

I fell down the rabbit hole of the latest Facebook version release, trying to understand the deprecation of their User Insights API. The story of the deprecation of the API isn’t told accurately as part of the the regular release process, so I found myself thinking more deeply about how we tell stories (or don’t) around each step forward of our APIs. I have dedicated areas of my API research for the road map, issues, and change log for API operations, because their presence tell a lot about the character of an API, and their usage I feel paints and accurate painting of each moment in time for an API.

Facebook has a dedicated change log for their API platform, as well as an active status and issues pages, but they do not share much about what their road map looks like. They provide a handful of elements with each releases change log:

• New Features — New products or services, including new nodes, edges, and fields.
• Changes — Changes to existing products or services (not including Deprecations).
• Deprecations — Existing products or services that are being removed.
• 90-Day Breaking Changes — Changes and deprecations that will take effect 90 days after the version release date.

The presence, or lack of presence, of a road map, change log, status and issue pages for an API paints a particular picture of a platform in my mind. Also, the stories they tell, or do not tell with each release paint an evolving picture of where a platform is headed, and whether or not we want to participating in the journey. Facebook does better than most platforms I track on when it comes to storytelling, by also releasing a blog post telling the story of each release, providing separate posts for the Graph API, as well as the Marketing API. It is too bad that they omitted the deprecation of the Audience Insight API, which occurred at the time of this story.

While I consider the presence of building blocks like a change log, road map, issues and status page a positive sign for platforms. It still always requires reading between the lines, and staying in tune with each release to really get a feel for how well a platform puts these building blocks to work for the platform. Regardless, I think these building blocks do adequately paint a picture of the current state of a platform, it just usually happens to be the picture that platform wants you to see, not necessary the picture the platform consumers would like to see.

• Read The Blog

As I keep an eye on the space I curate news, bookmark organizations, watch interesting tools, and work to understand what deployment solutions are being applied by leading API providers. I take everything I find and publish here as part of my research.

I then take this research, and what I've learned and publish stories on the blog, and more long form content like my industry guides, and white papers for customers. This is one way that I generate revenue to keep it all going.

If you'd like to see me focus more on API change logs I could use more partners investing in this area, helping me find the time to study more about what is going on. Feel free to contact me directly if you want to talk more about API change logs.

Thanks for your support!