Six Things You Should Include in Your API Style Guide

We’ve said it before and we’ll say it again: it’s important to design APIs consistently. Ensuring consistency across all your APIs means implementing and enforcing design rules for things like naming conventions, error handling, and security.

One of the best ways to make sure developers adhere to your design rules is to create a comprehensive style guide for them to follow. Here, we’re highlighting six things you should include in your API style guide.

Architectural Style

Should developers build APIs using REST, RPC, Hypermedia, or some other architectural style? Before you guide developers on which style to use, discuss which styles work best for different use cases. Choosing an API style can be tricky, as each one comes with a set of constraints. For example, some REST APIs adhere to the Hypermedia as the Engine of Application State (HATEOAS) constraint.

API Description Format

Once you’ve settled on an architectural style, choose an API data format to describe your APIs and include it in your style guide. You have several formats to choose from, including OpenAPI, API Blueprint, and RAML. In your style guide, tell developers that they should describe their APIs with the selected format.

We highly recommend OpenAPI, either v3.0 or v3.1. OpenAPI v3.1 was released early this year, and we’ve updated all our tools to accept OpenAPI 3.1 documents. If you’re unsure which version of OpenAPI to choose, we’ve published an article explaining some of the differences between versions 2.0, 3.0, and 3.1.

Naming Conventions

Without some guidance, each developer will independently decide what naming conventions to use, and things could get messy. You might end up with endpoints that have a combination of single nouns, plural nouns, and jargon. You could also wind up with endpoints and properties that have an inconsistent mix of lowercase and uppercase letters along with underscores and dashes. Once developers name things in an API, those names usually cannot change easily, as that can be a breaking change for API consumers. Including a section in your style guide that outlines naming conventions is well worth it.

Screenshot of Google Cloud APIs Documentation

The Google Cloud APIs documentation includes a comprehensive API design guide with a section on naming conventions. You can learn more about naming conventions in our latest podcast episode with Michael Hibay.

Error Handling

Include error handling in your style guide to make sure developers create error responses that look and behave consistently for users. Your style guide can help you standardize error codes, and error formats, keeping error handling consistent across all APIs.

You should design API error formats so that humans and machines understand what is happening when they receive an error. With your style guide, you can ensure that every developer approaches errors in the same way.

Screenshot of Facebook for Developers Documentation

The Facebook for Developers Graph API documentation includes an error handling guide that details error responses, error codes, and authentication error subcodes. For general advice about making good errors and picking error formats, check out this blog from APIs You Won’t Hate.

Authentication and Authorization

Security is one of the most critical areas of API design. In your style guide, explain how to design authentication and authorization flows according to safe practices. You might consider including security rules, such as:

• Never use “HTTP basic,” and always use HTTPS.
• Endpoints must include security in the form of OAuth 2.0 or an API key, but never both.
• Don’t use integers for IDs. Instead, use a universally unique identifier (e.g.: UUID).

You can describe a security scheme using OpenAPI, ensuring that developers treat authentication and authorization the same for all APIs.

Versioning

If you use versioning, include guidelines in your style guide so that developers update and deprecate APIs in the same way. You might include versioning rules, such as:

• Always apply version numbering to each API, explaining the numbering scheme.
• Never include version numbers in API URLs.
• Always include version numbers in API headers.

You have several choices when it comes to how you version APIs. For example, you might choose to version the entire API via the global URI itself. Or, you could version individual resources of the API. Either way, your style guide should make sure developers understand how to handle versioning.

A Style Guide for Consistency

You should include as much information as possible about your API design process in your style guide. However, you don’t have to include everything before you publish it. You could start with some of the items we’ve highlighted and then expand the content over time.

One of our goals at Stoplight is to make creating, sharing, and automating style guides easier. So, we plan on adding shared style guides to our platform in the near future (check back in a few months!). In the meantime, you can use a JSON/YAML Linter like Spectral to automate large chunks of your API style guides easily and validate API description documents automatically.

To learn more about style guides, visit our style guides page and download our Style Guide Best Practices sheet.