API Intersection
API Intersection
The Ultimate Guide to Style Guides & Design Reviews feat. Arnaud Lauret
Arnaud Lauret (the API Handyman), was featured on to API Intersection to discuss style guide best practices. As the author of the API Stylebook and the novel "Design of Web APIs," this Natixis Senior API Architect was the perfect guest for this topic.
In our recent podcast episode, we covered the six major style guide tips that will improve your developer experience and level up your API design. If you have a question to submit to our podcast, do it here: https://stoplight.io/question/.
1. Not All Who Design Are Developers
"I often work with API designers who are not developers and have more of a business analyst background. So, I decided to add in specific use case documentation to better help them understand the guidelines and apply that to their API development," - Arnaud Lauret.
Arnaud expressed how use case documentation is essential when working with API designers who don't have a developer background. The style guide focus for business-minded designers shouldn't be on the rules and rulesets, but on viewing the style guidelines as recipes. Arnaud alludes to designing APIs like shopping for a recipe and utilizing the guidelines as your shopping list to understand what components need to be designed.
Make your style guides easy to understand and apply to the real world because not every designer that stumbles across it will have a technically-minded background.
2. The Importance of Discoverability
"What do you want to do with your APIs, and how do you want to do it? And what are the rules of your domain? Why do you name it like that? Is it? I say these things every day. If you want to be a good API design reviewer, you must not be afraid to ask stupid questions, and it's really for the better. If you don't have discoverability of your APIs, you could be in trouble," - Arnaud Lauret.
One common problem with APIs is duplication of effort. If multiple teams are developing overlapping functionality, your company may have simply wasted it’s investment, and worse, created duplication of maintenance needs going forward.
Ensuring that new APIs are rationalized into a portfolio is essential (i.e. ensuring it makes sense, is reusable and doesn’t duplicate something that already exists). However, making sure that new designs are made available to the rest of the organization provides additional assurance that teams will connect on overlaps before investing code time.
Furthermore, sharing leverage of APIs builds reusability and overall synergy. If consumers of APIs can’t find the right thing to use because it’s not discoverable, you might end up with another source of duplicated effort.
3. Use Style Guide Automation to Drive Consistency
"Teaching people to understand the concerns of consistency is necessary. At the beginning, most people don't care about it or aren't aware of it, so it needs to be addressed." - Arnaud Lauret.
Automating style guides can quickly bring visibility to APIs which have design attributes which are inconsistent with the rest of the platform.. By eliminating (as much as possible) discussion about conventions which could be checked automatically, time is freed up to address bigger design questions than simple conventions. . Better yet, API reviews happen much faster, mitigating the risk that the API review process becomes a bottleneck to innovation.
Arnaud explains that for consistency, there are things within your style guides that you can fully automate and that which you can partially automate that will save you a lot of time later on. For example, Arnaud partially automates questions using Spectral, Stoplight's open-source linting tool that provides automatic validation and linting warnings.
Even with automation, building consistency takes time. Arnaud explains that it's often review after review, playing the long game to slowly but surely help people understand the critical role consistency plays in developing APIs.
4. Envision Governance from a Human Perspective
"There are two ways to do a design review. You can be a jerk, acting as a gatekeeper and policing all the rules….or you can do it the right way by showing empathy for the designer," - Arnaud Lauret.
It's critical to employ empathy when looking at governance from a global perspective and during an API design review. We've seen this theme trending in many conversations with API leaders, clearly it’s great advice.
When conducting an API design review, it's important not to enforce it as a method of control and job policing. As the reviewer, Arnaud notes that you need to take on the persona of a helping hand, explaining to designers that you are not there to tell them what they are doing wrong. Instead, you are there to explain design principles and provide value for how the API design can be modified or fixed. Based on the designers' context, discuss their needs and build it together.
In the end, the API designer gets to make the final decision, as they are the domain expert. Arnaud finds this approach works exceedingly well.
5. Apply Your Design Thinking on a Larger Scale
"The API design you are preaching and the tips you're using to create good style guides are actually principles that you can apply everywhere," - Arnaud Lauret.
As one goes through the process of design thinking, the questions you're asking yourself and solutions you are solving can be applied everywhere, not just to style guide implementation and API design. In fact, those same principles of success can be applied to user experience in making things that are actually fulfilling, to solutions to existing programs, to mobile apps, and more.
When developing any kind of system in general, there is a design component that people often get wrong: it has to be easy to understand. Many people will take a comprehensible system over a high-performing one any day. If you can understand how something works and how to replicate it, you're much more likely to use it and keep utilizing it in the future.
Design thinking goes far beyond the world of APIs, but it's a great practice to apply the same concept to larger-scale programs, products, and technology teams. Digital and platform transformations often require infusing design thinking across the organization, API design is simply one facet.
6. More Resources on Creating Successful Style Guides
For more, check out our full podcast episode with Arnaud or his API Stylebook. As for other guides and resources around proper style guide creation, implementation, and API program scaling, see our list of resources below.
