API guidelines, what they are, and best practices for how to create, use, and enforce them at your organization.
Public style guides are available for Professional and Enterprise workspaces. Simply login to your workspace, click on the Governance tab, and look for Public Style Guides, then enable the rules you want to use. Public Style Guides are sets of curated rules from top companies around security and design themes. API Program leaders can implement these preset style guides with a few clicks. Use Public Style Guides to inform your own API style guides and tweak the rules according to your needs, or enable a preset guide to use out-of-the-box best practices in your Stoplight projects.
Sign up here to get notified about the latest Public Style Guides release.
API style guides, or API guidelines, are easy-to-consume references and instructions for all of the important information that a team will need to create or work with APIs. The style guide gives specifics about functions, classes, return types, errors, arguments, and more, and can be used to enforce standardization across an API program.
This API style guide reference will help give you a basic understanding of API guidelines, what they are, and best practices for how to create, use, and enforce them at your organization.
If you asked 100 developers which naming conventions to use where in an API spec, you’ll either get 100 answers or an all-out brawl. To save this from happening, most API teams that grow beyond a handful of developers will implement a style guide.
Also known as "API Design Guides," "Design Guidelines," "Style Books," or "API Standards," the simple concept of "make a bunch of decisions and write them down" has helped API teams for decades be more consistent, develop faster, and create better APIs.
These style guides might contain rules about how to handle versioning, filtering, error formats, naming conventions, pagination, or any of a million other variable parts of an API, helping take the burden off of teams about making those different decisions.
An API style guide ensures everyone on the team follows basic API design patterns.
But the real benefit is for your developer experience. API consistency equals predictability, and it makes it easier for internal and external developers to work with your APIs. When your API is delightful to use, adoption and retention increase.
Remember: customers that build products using your API are stickier than those who don’t. As more teams within the customer’s company continue to integrate with the API, the better prepared you are to expand.
Source: 7 (Not So Deadly) Steps to Create a Successful Developer Relations Program
For your API style guide to be most effective, it should cover several common API design themes and be written in a way that is:
Check out our Style Guide Rulebook series for more API style guide best practices.
Here are some of the common design themes you should include in your API style guidelines.
One of the first points to cover in your API guidelines is defining the overarching architectural style. Should your organization or team follow REST, GraphQL, or a different design pattern?
In addition, you’ll want to let developers know whether they should be describing their APIs with some kind of specification (hint: they probably should), and if so, what that specification is.
One important aspect of API design is security. In addition to design style, security should be one of the major themes in your style guide. In particular, style guides should explain how developers should implement authentication and authorization.
Some of the top authentication frameworks include:
Usually, OAuth v2 is the industry-standard protocol for authentication.
Path naming is important although some types of API (especially REST/Hypermedia APIs) consider an URL to be opaque, developers exploring an API will often type those paths whilst playing around with an API, and having consistent naming conventions and guessable URLs improves integration time. Make your URLs simple, consistent, and universal.
Consider HTTP error codes as another critical component of your API guidelines. For example, some teams may decide to use 400 Bad Request for data validation errors, others may use 422 Unprocessable Entity, and maybe one team reads the HTTP spec wrong and decides to incorrectly use 406 Not Acceptable. Your style guide can pick one, and generally help people make better quality API errors to help computers and humans.
Versioning and breaking changes and how to treat them can vary between organizations. Be sure to highlight how to treat versions and breaking changes in your API guidelines, and update this section as your versions evolve.
Define the units, formats, and standards that developers should follow in your API style guide. What to define can depend on your industry, but “some types of data — like date-times — are relatively universal.”
Source: 11 Tips for Creating an API Style Guide
Now that you know what to include in your API guidelines, here are some best practices for creating excellent style guides that your organization will adopt, contribute to, and want to use.
Create an easy-to-consume style guide that is brief yet thorough. Developers should be able read the entire style guide, but it should also be comprehensive enough to provide consistency for even small considerations.
One way to create a more comprehensive style guide is by, “frequently linking to external resources, where specific standards or best practices are described in more depth. These can be your organization’s own resources or even trusted third-party resources.”
One of the best ways to illustrate and show an idea is to include an example. Build in sample requests and responses throughout your style guide. Sometimes it helps to include several requests and responses to show how developers should—and should not—design their APIs.
Work across your team to collaborate on your API style guide. Encourage developers to submit feedback or request help on their API designs. Cross-team collaboration will improve buy-in and increase adoption of your guidelines.
Evangelizing your API and style guide with the developer community can also help enforce consistency. This helps showcase the thought you’ve put into your API and helps you get good feedback from those using your style guide.
Source: 11 Tips for Creating an API Style Guide
For years API style guides have been written as text-based documents, and you had to either hope API designers and developers took the time to read through it all and keep up-to-date with changes, or run API design reviews where some folks who had memorized the whole thing would check every minor detail of the API against it. Neither are particularly efficient, so Stoplight have created automated tooling which can help enforce style guides programmatically.
This entirely free tool is integrated with Stoplight, VS Code, or Jetbrains IDE, to guide design/development decisions early on in the process, or it can be used via the CLI to enforce the style guide via continuous integration.
Organizations large and small around the world have published their API Style Guides as Spectral Rulesets so they can distribute and enforce style guides across their entire organization, with some key examples being Adidas, Azure, Box, Digital Ocean, and the Italian Government many of which are published for you to try out, or at least use as inspiration.
Learn more about Spectral and building custom rulesets for your API Style Guide.
Stoplight has created Style Guide Projects, a convenient hosted version of Spectral's Style Guide offering, to make creating, sharing, and enforcing style guides far easier, especially for non-technical users as setting up Spectral in various editors, enabling it in pull requests and setting up rulesets distribution can take a fair bit of work.
Instead of having to glue together all the pieces, your Style Guides will be right there in Stoplight Platform, giving API designers and developers feedback as they work on the APIs.
Learn more about creating Style Guide Projects, and all the powerful things you can do with them once they're built.
However the style guide is created, enforced, and distributed, establishing and producing a consistent Style Guide is crucial to developing a successful API. You want customers to work with you and use your APIs because you help them solve problems. In order to make it easy and delightful to work with your APIs, you need proper documentation, an easy and predictable process, and a strong rally around consistency.
You can also check out Stoplight’s open-source linting tool, Spectral, to help you create further consistency and standardization in your API program. Spectral is a linter that allows you to create style guides for your structured data. Things like OpenAPI/AsyncAPI/RAML descriptions, Kubernetes config, GitHub Actions, you name it, Spectral can help you lint it.
Contents
