There has been a growing trend among API teams to better standardize their API design process. For many, the effort to standardize API design starts as an internal exercise to make sure that everyone involved in designing, developing, and testing APIs are on the same page.
Design guidelines may be published internally as a PDF or on an internal Wiki for everyone to reference, and processes are put in place to make sure teams are following the design guidelines. But many companies take this a step further and publish these guidelines publicly as a reference for developers working with their APIs, and anyone else that wants to learn from their experience. Arnaud Lauret (better known as the API Handyman) is the creator of API Stylebook, an online resource dedicated to helping API developers solve their API design challenges by learning from organizations that have effectively implemented a process for standardize API design. Arnaud has reviewed style guides from organizations across a wide variety of industries, including Cisco, Google, Paypal, Microsoft, and others, and compiles his findings in one easy-to-navigate resource.
I recently had the chance to speak to Arnaud about how API Stylebook came to be, and to get his advice for organizations that are starting the journey of setting up API design guidelines of their own. As Arnaud explains, creating internal style guidelines is the just the beginning of the process. Read our full interview below to find out what comes next, and what lessons Arnaud has learned from his work on API Stylebook.
What inspired you to create the API Stylebook as a resource for API designers?
I created the API Stylebook because I struggled a lot to find solutions to basic API design problems and I thought that I was probably not the only one. When I started to design REST APIs, many of my basic API design problems were not easily solved. It was difficult to find information about how people who faced similar challenges solved them. Sometimes I didn’t find any answers to my questions. And I was not aware of all matters you have to think about when designing APIs.
With experience, I forged my answers which were sometimes good and some other times terrible. I also realized that I had missed some important aspects. What bothers me most beyond having to live with some of the design mistakes is that these mistakes are so common in the industry that nobody should make them. These are problems that have been solved so many times that nobody should have to lose time solving them again. I wanted to do something to help people not make the same mistakes and lose time. This is how the API Stylebook started. I realized at that time that more and more companies and public organizations were sharing the way they were designing APIs by making their guidelines publicly available. All these guidelines contain answers to common API design problems.
I started to collect them having the objective of simply providing a list of links. But as I was reading them, I realized that simply providing a list of links may not really help designers find solutions quickly. As they are all very different from each other — in their organization or the vocabulary used — it could still be a real burden to find a solution. So, I decided to list all topics covered by these guidelines and normalized them to provide quick and direct access to them. And thus, the API Stylebook was born.
How do you select the design guides that are covered on API Stylebook? Are there certain criteria you look for when evaluating style guides?
There are probably thousands of blog posts talking about API design but I only want to provide material which has been confronted in real world scenarios. That’s why I only add “official API design guidelines” that are really used by the companies to the API Stylebook.
Why do you think more companies are focusing on standardizing their API design?
The most obvious reason of why a company would establish guidelines is that the more APIs that are developed in an organization, the more you need them to be consistent with each other. Providing APIs which share common behaviors, patterns, and a standard look and feel will greatly ease the work of the people who want to use them, whether they are from the company or not. Another reason could also be efficiency in API design. With guidelines, API designers can focus on what really matters instead of losing time discussing endlessly about tiny details or trying to solve design problems that already have been solved within the company.
I know that you’ve spoken and written a lot about OpenAPI. Do you see companies incorporating standards like OpenAPI into their API design guidelines?
Not enough IMHO :-) I have only spotted two (Haufe and Zalando) on the API Stylebook. But Zalando is definitely the best example of how to use OpenAPI. They use the OpenAPI specification in the design phase, store it in version control system, and control API design with a custom tool called Zally. This is brilliant! We need more tooling around OpenAPI and design control. Zalando also provides some hints about to to describe data accurately using the OpenAPI specification.
Two topics that we see come up a lot are Governance and Versioning. How do you see organizations handling governance in their API style guidelines.
Governance covers a lot of topics from why we make API to how they should be designed and how to handle their lifecycles. API design guidelines may cover some of these topics but not all of them. Governance topics besides versioning are not really well represented in guidelines I have analyzed. They focus mainly on how to design API and less about the rest. But still, some guidelines talk about deprecation (Zalando or Atlassian) or API design validation process (Haufe). I sense that governance guidelines should be described in one or more other documents to avoid mixing too different concerns.
Versioning, which is definitely a governance topic and is tightly coupled with design, is more present in guidelines. It is usually presented through how to call a specific version of an API. There are various strategies like using URL or content negotiation. But knowing how to differentiate two versions of an API is nothing if you don’t know if the changes you are making are breaking or not, and only a few guidelines provide information about this.
Google provides some hints, but again Zalando is the most complete on the subject
Is there other advice, or lessons you’ve learned through your research, for organizations that are starting the process of implementing API style guidelines?
Don’t dare to think that the work is done once you have written guidelines. Guidelines must evolve because they will not cover all possible problems at first. And most important nobody will read them nor respect them without promoting them, and controling what is done. If you want to know more about the why and the how of API design guidelines, you should come at APIStrat and attend to my session The Lord of API Designs.
Thanks for reading! Looking for more API resources? Subscribe to the Swagger newsletter. Receive a monthly email with our best API articles, trainings, tutorials, and more. Subscribe