In our last post, we gave you some tips on how to assess your API style. Whether you’ve got a consistent style or not, an API style guide is an important tool in your governance toolbox. API style guides help you reflect on your practices and codify them to make future compliance easier.
Getting started building your own API style guide can be daunting. There’s a lot of information to consider as you think through your options – from general tip sheets to in-depth analysis from industry-leader blogs. You’ll certainly want to look at information from a wide range of sources to guide your decisions. It can also be helpful to look at some real-world examples to get a sense of what works for other organizations.
We’ve pulled together a list of a few of our favorite “in the wild” API style guides from a diverse group of companies, along with our commentary on what makes them work so well. First, though, it’s important to get a handle on what every API style guide needs to include.
What Good API Style Guides Have In Common
Good API style guides have several things in common, as you’ll see in our list below. The purpose of an API style guide is to make it easier to achieve consistent, appropriate style across your API offerings. It’s also to ensure that your APIs meet developers’ expectations for APIs in general, making your APIs easier to build and use.
The APIs in our list below are all REST APIs – there are other architectures out there, but that’s our focus here. REST APIs are also what Stoplight Platform supports. As you start to dig through our list of style guides, you might notice that many of them reference a doctoral dissertation by Roy Fielding. Fielding’s dissertation is what laid out the basics of REST architecture, which is likely already familiar to you and your development teams. Similarly, some guides include links to the IETF’s REST Framework. Those resources are there if you want them, but chances are, you already know most of what’s spelled out there.
A successful API style guide will cover Fielding’s basics and layout details in six areas:
- Architectural Style: As we mentioned, we’re primarily looking at REST architecture in this guide, but there are other choices out there that you may want to consider, like GraphQL.
- API Description Format: We highly recommend OpenAPIand offer tools to support it!
- Naming Conventions: Consistent naming conventions let developers work more efficiently. Agree on a standard from the beginning. Renaming endpoints is a breaking change.
- Error Handling: Standardizing error codes and formats helps developer productivity. Error messages are also a place for you to convey some of your ‘persona’ as an organization and build rapport with your users!
- Authentication and Authorization: APIs can be a security challenge. It’s essential that you establish a comprehensive approach to security for your API, and cover relevant details for your developers in your style guide.
- Versioning: Once you’ve made choices about your versioning policies, you need to include those rules for how versions should be reflected in your endpoints and headers.
All of the API style guides in our list below cover these crucial content areas. They also implement some important aspects of ‘form’, as well. A successful API style guide needs to be:
- Navigable: Let users find what they need quickly with navigable headings and links.
- Organized: An API style guide is a functional document, so logical segmenting and ordering of your content is very important.
- Digestible: Your developers need to be able to grasp the rules quickly and see the rationale laid out succinctly.
- Flexible: Whether you use a Git repository or a more sophisticated tool like Spectral, you need to set up your API style guide to accommodate changes over time _without_ creating the confusion of multiple documents reflecting outdated guidelines. Your API style guide will evolve, so start with a framework that makes changes easy to propagate and enforce.
Choose An Approach That Meets Your Unique Needs
We’ve been talking about consistency a lot, and that is really the driving principle behind API style guides. As we discussed in our last post, there are an enormous number of choices and no one right answer.
There’s no one-size-fits-all solution, so you need to create something that will get buy-in from your teams. Consider the following factors:
- Ownership: Top-down or collaborative? Whether you choose a top-down approach with a centralized API team drafting your guide or building your guidance collaboratively with a cross-functional committee should depend on your organizational culture.
- Tone: Are your development teams used to communications being formal, or will they prefer something more relaxed? You want your development teams to feel comfortable accepting the rules into their daily workflow, so you’ll need to consider where your tone should land.
- Depth: Will your teams prefer detailed explanations of guidelines with citations, examples, and reasoning, or will they prefer a list of bullet points? You’ll want to include the details somewhere, even if you emphasize the ‘hit list’ version, but your teams’ decision-making process and workflow should inform how much information you put upfront.
- Access: How will your API developers learn about updates to your guide? How will they interact with it as they work? Small teams and companies with a limited number of APIs may be able to get away with distributing a document and managing notifications and compliance manually. But as organizations get larger and products get more complex, you will likely want to consider automated options like Spectral.
The guides below deal with these choices in a variety of ways, reflecting the needs of a diverse group of organizations. Many more API style guides are available on Arnaud Lauret’s terrific API Stylebook – check it out for inspiration after looking at our chosen examples!
API Style Guides We Love
PayPal
PayPal’s API style guide is just about the most comprehensive guide we’ve seen. Their effort makes sense – reliability, and predictability are never more important than when dealing with payment systems. The guide includes extensive detail on the ‘how’ and ‘why’ of each rule, making both process and rationale clear for devs. The publicly available version on GitHub is not the most elegant document, but it has a navigable and highly granular table of contents that can get users to the information they need quickly.
Atlassian
An enormous number of people and organizations around the world use Atlassian products, so nailing developer experience for their APIs is extremely important for them. Their API style guide is comprehensive, easy to navigate, and delivers the professionalism and efficiency we’d expect from Atlassian. One note – because these guidelines are aimed at developers who may be outside the Atlassian organization, specifically Atlassian customers building custom plug-ins, there is no built-in automated enforcement. Internally, Atlassian has different processes for their development teams that do include some automated tools.
Haufe Group
Haufe is a European software company working mainly in business services, and, like Atlassian, they’ve developed an API style guide that reflects a more formal corporate culture. Visually, it’s clean and uncluttered. It lacks the hyperlinked headers in Atlassian’s guide, instead of relying on a navigation sidebar. Using GitBook is an in-between option for versioning and automation, allowing version control and easy dissemination.
Zalando
Haufe cites Zalando’s API style guide as a source of inspiration, and we love it, too! The Table of Contents is longer but includes every policy right up front in plain language. It’s very easy to go deeper and get detail on the ‘why’ of each rule. In terms of maximizing developers’ efficiency, the list approach is great. Zalando is a European e-commerce company, and its API style guide captures a bit of the youthful, design-centric culture of the company. Zalando has its own linter called Zally for its style guide work.
Adidas
Adidas is another Spectral user, but that’s not the only reason we like the Adidas API style guide! The interface of the text version of their style guide on GitBook is concise and transparent, with a nice balance between explaining the ‘why’ and getting developers the necessary information quickly. They place emphasis on key principles by linking between rules, and by highlighting them in a “General Guidelines” section. More detail is easy to access, and the core principles are distilled in a way that conveys the purpose of the rules, focusing on what matters most.
There are many factors to consider at every phase of API design and implementation, but practical examples can help you develop a sense of what will work best for your organization. We hope that perusing these examples of good API style guides will help you as you plan your own! We’re here to help too, with expertise and tools for every step of the process.
Check out our best practices for API style guides and style up with Stoplight, and stay tuned for more information to come soon on some exciting new style guide features in Stoplight Platform.
