Crafting and Publishing API Design Guide Shows That You Are Further Along In Your API Journey

I spent all day Wednesday, at Microsoft offices in San Francisco, providing feedback on the Microsoft API design guide, as part of the OneAPI Technical Advisory Group. The OneAPI team had already done most of the hard work in hammering out the API design guide, by working with the API leadership from groups across Microsoft--we were just brought in to provide outside perspectives.

A group of about 20 of us, spent the entire day walk through the high levels of the Microsoft API Design philosophy. The Microsoft OneAPI design guide is a draft, so they aren't ready for us to share it publicly, something we'll see in the near future. However, document being ready or not, the process showed me that Microsoft is really working hard to get their API design strategy house in order. They had worked hard to iterate through all the common areas of API design, with their various teams--even some of the more controversial areas like versioning.

I did not feel like I had a lot to contribute to the process. They have some really good API designers, and there was plenty of high quality API design talent in the room, to provide the feedback they wanted. When Microsoft is ready for more of the management, evangelism, and other areas more in the business and politics of APIs, I will have much more to bring to the table. I did however, provide some insight that I think could help the overall process, and will continue to provide feedback--which is why I'm gathering my thoughts in this series of posts.

Prior to me participating in the OneAPI Technical Advisory Group, I had just published the API design guides for Cisco and Paypal, as part of my API design research. Bringing the number of API design guides to 9, which is a good sign the space is getting more serious about standardizing how we do API design. For me, there are two important things going on here:

  • Company Journey - The companies own API journey, allowing them to collaborate and craft a single API design philosophy, with the intent of making it a company-wide initiative.
  • Publicly Sharing - Declaring to the public, this is how we design APIs. Something that allows others to learn from, and merge with their own API design philosophy--benefiting the entire space, while also establishing leaders and followers.

Crafting a document that defines how a company builds software is nothing new. However, APIs aren't just about building software, they are about defining your companies resources, and when you work to standardize how you define your resources as APIs, you are focusing on the core of your business. Next comes the value when building websites, web and mobile applications, and potentially devices as well. Getting your API design house in order, is all about standardizing how you speak API across your company, something that touches every product and service, and is the foundation for your corporate digital strategy.

My participation in the OneAPI Technical Advisory Group gave me a unique glimpse at the API strategy unfolding at Microsoft. While there is still a lot of work to be done, the fact that they are working on a central API design strategy demonstrates to me they are further along in their API journey than I thought they were. Where are you in your own API journey? Does your organization have an API design guide? How do you share this knowledge across your organization, and with the public?

As I monitor the API space, I am always looking for the signals of a healthy API strategy, and I think, when I see a formal API design guide present for any company that I track on, I am going to tack on a couple extra points. A polished, publicly shared API design guide shows organizations are a further along in their overall API journey, than other companies in the space, who are still trying to figure things out.