An API style guide is one of the most effective tools for maintaining consistency across a suite of APIs. Many large enterprises already have some kind of development style guide, but even smaller platforms are beginning to implement this proactively, along with other API governance best practices — and so should you!

For an API style guide to be most beneficial, it should cover several common API design themes and be written in a way that is clear, easy to update, and actionable. In this post, we’ll cover 11 crucial tips and must-haves to bear in mind when creating your organization’s API style guide.

Must-Have Items for Any API Style Guide

Let’s start by discussing the basic items an API style guide should include:

1. Design Style and Specification

One of the first things a style guide should cover is what overarching architectural style to use. For example, should APIs adhere to REST, GraphQL, or another design pattern?

Alongside this, 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.

2. Authentication and Authorization

An extremely important aspect of API design is security, so second to design style, it should be one of the top themes in a style guide. In particular, style guides should explain how developers should implement authentication and authorization.

In most cases, such as that of the Cisco API Design Guide, this will mean using OAuth 2.0 — an industry-standard protocol.

3. Endpoint Naming

According to a senior PayPal engineer, the naming of API endpoints is an often underlooked aspect of API design, even though these names tend to stick around. As a result, it’s worth dedicating a small section of your design guide to naming conventions — see our guide here for endpoint naming best practices.

4. Error Codes

Another critical consideration for your style guide is the use of HTTP error codes. Although they shouldn’t vary too much between organizations, the specifics are still worthy of inclusion in your style guide.

If you’re not sure what exactly to discuss in this section, check out our guide to best practices for error handling.

5. Versioning

How versioning and breaking changes are treated in APIs can vary from organization to organization, so this is another thing to include in your style guide to ensure your APIs evolve in a similar fashion.

Once again, we have a complete guide to best practices for versioning!

6. Units, Formats, and Standards

Last but not least, it’s worth defining the units, formats, and standards that developers should adhere to within your API style guide. What you have to define will often depend on your industry, but some types of data — like date-times — are relatively universal.

For information on some of the standard date and time practices used in API development, see this resource by API architect Jason Harmon.

More Tips for an Effective API Style Guide

Getting the scope right is only half of the battle of creating a good API style guide. The rest is making it clear, easy to update, and actionable. For that, refer to these tips:

7. Use a Version Control Tool

Although an API style guide could take the form of a regular plaintext document that gets distributed on Slack, we strongly encourage a more iterative solution that allows you to transparently update the guide for everyone to see.

GitHub is a great tool for this — heck, both PayPal and Microsoft, among others, house their API style guides within public GitHub repos.

Another solution is to iterate on your style guide using a version control tool like GitHub, but render a static version with your own styling elsewhere. This is precisely what Google has done with their API Improvement Proposals — the source is on GitHub, but a prettier static version is rendered at https://google.aip.dev/.

8. Use RFC Requirement Levels

It’s not a must, but you should consider standardizing requirement levels in your style guide using the keywords outlined in RFC 2119. This way, developers will know exactly how to interpret your guidelines:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

9. Frequently Link to External Resources

Your style guide should be brief enough that developers can read it in its entirety, but it should also be comprehensive enough that the most mundane aspects of API design can be consistent across your suite.

One way to achieve this 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.

10. Insert Request/Response Examples

Often, the best way to illustrate things is with examples. In the case of APIs, that means showcasing sample requests and responses frequently in your style guide.

It can be particularly helpful to include two pairs of requests and responses to show how developers should and shouldn’t design their APIs.

11. Encourage Collaboration

Our final tip is to enable collaboration on your API style guide. At the very least, developers from across the organization should be able to submit feedback or request guidance on specific areas of API design.

This is yet another benefit of using a version control platform like GitHub — it provides a familiar environment for collaboration. Again, Google’s API Improvement Proposals is an excellent example of cooperation and transparency in API style guide maintenance.

Conclusion

As Chase Doelling describes, “scalable APIs are built from consistency.” Thus, an API style guide is an easy and effective governance tool for maintaining consistency across your API suite. In this post, we looked at six items any style guide should contain and five tips for making style guides as useful as possible!

For more information on what to include in your style guide, check out the API Stylebook by Arnaud Lauret. It’s a compilation of design guidelines from over a dozen leading tech organizations — including Atlassian, Cisco, and Microsoft — categorized by topic.