API Design Industry Guide: API Stylebook

This post is from the latest copy of my API Evangelist API Design Industry Guide, which provides a high level look at the API design layer of the industry. Providing a quick look at the services, tools, and some of the common building blocks of API design. The guide is heavily rooted in REST and hypermedia, but is working to track on the expansion of the space beyond just these formats. My industry guides change regularly, and I try to publish the articles from them here on the blog to increase their reach and exposure.

Arnaud Lauret (@arno_di_loreto), the API Handyman (@apihandyman), has been developing an API Stylebook that provides a collection of resources for API designers. It is a brilliant aggregation of thirteen API design guides from Atlassian, Cisco, Cloud Foundry, Google, Haufe, Heroku, Microsoft, PayPal, Red Hat, The White House, and Zalando. It highlights best practices used by leading API providers.

“The API Stylebook aims to help API Designers to solve API design matters and build their API design guidelines by providing quick and easy access to selected and categorized resources”, says Lauret. A unique community resource, it provides deep linking to specific topics within publicly available API design guidelines. Instead of reinventing the wheel or searching Google for hours, API designers quickly can find solutions and inspiration from these existing best practices.

More than just a list of guidelines, it is a machine readable distillation of the thirteen API design guides into a master list of API design topics you can consider when crafting your own API design guide. It is slick. I like Arnaud’s approach to analyzing the existing API design patterns across the API platforms who have shared their guides. I also really like the YAML approach and it’s presented as a very good looking website using Github, and Github Pages.

This is how API literacy tools should be constructed and it provides a valuable lesson in API design. You can take that lesson and execute what you’ve learned along the way, with a very hands-on process. Using the API Stylebook, you can craft an API design guide for your team to follow and employ across API operations. Anyone can fork the API Stylebook, pick and choose the best practices across the thirteen API design guides, and then publish a version as a Github repository. The resulting repo can easily be included in your API docs, as a standalone website.

There are two things going on here. First, API providers are sharing their views on API design best practices — important stuff. Second, an aggregator (API Handyman) makes these best practices machine-readable, forkable, and reusable. This knowledge layer of API operations becomes even more valuable when it is openly accessible and shareable in this way. We need our APIs to employ common patterns and speak in common formats so that they’ll work together and reduce friction in the industries where they being put to work. API Stylebook approaches API design through continuous integration, allowing API development groups to define API methodologies that can be deeply integrated into our lifecycle.

The more API design guides that are sourced in the API Stylebook, the better the available topics will become. Arnaud will be adding new API design guide to the stack. It is better for the community if you start with his existing list of topics and add your own YAML definitions that drive the API Stylebook on Github, but we’ll take what we can get. It is a process that every company, organization, institution and government agency should go through and what you learn along the way is essential for any API team.

API design isn’t just knowing the details of REST or any single architecture pattern. It’s the knowledge you gain from the definition process, and a huge part of this process is having an effective pool of community knowledge to pull from. Arnaud has done an amazing job at processing disparate and unstructured API design and yielding coherent list of topics that we can all consider in our own API design process. We should all be investing in (and building on) his work.It is something I’m baking into my API design research wherever I can — dovetailing the common building blocks I’ve aggregate across his very detailed work.

REST is a philosphy, not a standard. The current wave of web API success we see across the technology landscape has been about API providers building on top of the best practices of the web API providers that came before them, going back to the early pioneers of SalesForce, eBay, and Amazon. Every API architect I know has learned from reverse enginnering and studying the practices of what they’d consider to be well designed APIs, and understanding the bad design practices out there. If knowledge isn’t shared, then the next generation of API developers do not learn from what came before them. Making the practice of publishing your API design guide for your API not just good for your own API operations, but good for the entire API community.

The most significant API movements in the last five years came from Apiary in my opinion, but the most significant API movements in the next five years will be about sharing API design patterns on Github. Allowing API providers to borrow from each other, resuse, and communicate around common API patterns that are working, or not working. API definitions are allowing us to publish these common design patterns to Github, and the next generation of continous integration and deployment tooling like API Stylebook allow us to publish, share, and even test the quality of our APIs.

I will be continuing to invest in API Stylebook, writing stories about it, and helping API providers understand the value of the open source project and sharing of their own API design patterns, and since it’s machine readable, I will be integrating the API Stylebook into all of my API design research.

Get A Copy Of The API Evangelist API Industry Guide