The new Style Guide Projects feature is now available in preview mode for new workspaces. If you have a Professional or Enterprise level account, contact us to learn more. Read this documentation to learn more about Style Guide Projects here.
Some members of the Stoplight community may have noticed that we are practicing a celebration of “Style Guide September” this month at Stoplight. So, it felt fitting to invite my colleague, Arnaud Lauret (the API Handyman), 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.
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.
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 their 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 the 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.
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 that have design attributes that are inconsistent with the rest of the platform. By eliminating (as much as possible) discussion about conventions that 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.
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 them 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.
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 the 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, solutions to existing programs, 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.
Follow Style Guide Thought Leadership
For more, check out our full podcast episode with Arnaud. As for other guides and resources around proper style guide creation, implementation, and API program scaling, see our list of resources below.
- API Style Guide Best Practices
- Style Guide Tooling
- What to Include in Your Style Guide
- Style Guide Overview
Podcasts like the API Intersection, and indeed Arnaud’s own website are excellent resources for leveling up your API style guides. Follow the conversations on LinkedIn and Twitter happening every day to stay up-to-date and inspired.
