A API style guide is one of the most effective tools for maintaining consistency in a set of APIs. Many large companies already have some sort of development style guide, but even the smallest platforms are beginning to proactively implement this, along with others. API governance best practices And you should too!
For an API style guide to be most beneficial, it should cover more themes ale API aspect usually and be written in a clear, easy to update and actionable manner. In this post, we’ll cover 11 tips and essentials to consider when creating your organization’s API style guide.
Essentials for any API style guide
Let’s start by discussing the basics that an API style guide should include:
1. Design style and specifications
One of the first things a style guide should cover is the general architectural style to use. For example, if APIs adhere to REST, or GraphQL another design model ?
In addition, you will want developers to know if they should describe their APIs with some kind of specification (hint: probably should ) and, if so, what is the specification.
2. Authentication and authorization
An extremely important aspect of API design is security, so following the design style should be one of the main topics in a style guide. In particular, style guides should explain how developers should implement them authentication and authorization .
In most cases, such as the one in the Cisco API Design Guide , this will mean use OAuth 2.0 , an industry standard protocol.
3. Terminal nomenclature
According to a senior PayPal engineer , the name of API endpoints is an aspect often overlooked in API design, although these names tend to remain. As a result, it is worth dedicating a small section of your design guide to naming conventions; see our guide here for best terminal naming practices .
4. Error codes
Another critical consideration for you Stylistic guide is the use of HTTP error codes. Although it should not vary too much between organizations, the details are still worth including It is Stylistic guide.
If you are not sure what to discuss in this section, see our guide best practices for handling errors .
5. Version control
The way what the version and important changes APIs can vary from organization to organization, so this is another thing to include in your style guide to ensure that your APIs evolve in a similar way.
Again, we have a complete guide for best practices for version control .
6. Units, formats and standards
Last but not least, it’s worth defining the units, formats, and standards that developers need to follow in their API style guide. What you need to define will often depend on your industry, but some types of data, such as dates and times, are relatively universal.
For information on some of the standard date and time practices used in API development, see this resource from API architect Jason Harmon.
More tips for an effective API style guide
Getting the right scope is only half the battle in creating a good API style guide. The rest must be clear, easy to update and actionable. To do this, see these tips:
7. Use a version control tool
Although an API style guide could take the form of a simple text document that is distributed on Slack, we strongly recommend a more iterative solution that allows you to update the guide transparently so that everyone can see it.
GitHub is a great tool for this; Hell, so much PayPal What the Microsoft , among others, host their API-style guides in GitHub public repositories.
Another solution is to iterate through your style guide using a version control tool like GitHub, but play a static version with your own style elsewhere. That’s exactly what Google did API improvement proposals : source is in GitHub , but a more beautiful static version is presented in https://google.aip.dev/ .
8. Use the RFC requirement levels
It is not mandatory, but you should consider standardizing the requirement levels in your style guide using the keywords described in RFC 2119 . This way, developers will know exactly how to interpret your rules:
The keywords «SHOULD», «SHOULD NOT», «NECESSARY», «SHOULD», «SHOULD NOT», «SHOULD», «SHOULD NOT», «RECOMMENDED», «MORE» and «OPTIONAL» of this document are for interpretation. as described in RFC 2119.
9. Frequent connection with external resources
Your style guide should be short enough for developers to read in its entirety, but it should also be comprehensive enough for more mundane aspects of API design to be consistent throughout the suite.
One way to do this is by frequently connecting 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. Enter sample request / response examples
Often the best way to illustrate things is with examples. For APIs, this means frequently posting sample requests and answers in your style guide.
It can be especially useful to include two pairs of questions and answers to show how developers should be. should not be design your APIs.
11. Encourages collaboration
Our final tip is to enable collaboration in your API style guide. At the very least, developers across the organization should be able to provide feedback or ask for guidance on certain areas of API design.
This is yet another advantage of using a version control platform like GitHub – it provides a familiar environment for collaboration. One more time, Suggestions for improving the Google API they are an excellent example of cooperation and transparency in maintaining the API style guide.
What the describes Chase Doelling , «Scalable APIs are built on consistency.» Therefore, an API style guide is an easy and effective governance tool for maintain consistency throughout the API set . In this post, we look at six elements that any style guide should contain and five tips to make style guides as useful as possible.
For more information on what to include in your style guide, see Stylebook API by Arnaud Lauret. It is a compilation of design guidelines from more than a dozen leading technology organizations, including Atlassian, Cisco and Microsoft, sorted by topic.