Enforce an API Style Guide in Your Organization
What to include and how to keep your APIs consistent
May 23, 2019
Photo by Tabea Damm on Unsplash
Making a great API is no easy task. Just defining what qualifies as a great API can be difficult to pin down. There are, nonetheless, some effective strategies that can be applied universally for modern, RESTful APIs. These strategies will assist not only API consumers, but also API developers moving forward. For the first piece in this series, I will be discussing broader industry wide strategies including: defining your audience, future proofing, consistency and conciseness, and a brief introduction into the importance of documentation.
Defining your API consumers’ needs is critical to building a strong foundation for your API. Your API is, in fact, a product, and like any product, should be designed around who is going to be using it. Some questions that need to be addressed before designing your API include:
Being able to answer these questions before designing your API will ensure that the design meets your users needs and decreases overall design time.
With such an abundance of formats, choosing one that meets your users needs and is future proof can be overwhelming. The paradox of choice has levelled many a developer. Luckily, the industry at large has adopted some standards that help make this decision simpler.
GraphQL is a reliable alternative as well (we even use it some at Stoplight), but REST’s history and adoption make it a safer choice in the long run
Maintaining a clear, concise structure for your API will pay dividends in the long run and will promote long term API success. When designing endpoints, a defined naming strategy will help your users and other developers working on your API. This can ultimately be achieved by putting together an API style guide which will promote conciseness and consistency throughout your organizations API design process. API style guides should describe naming and design conventions so that developers and consumers can predict your APIs behavior and should also help eliminate design errors. Utilizing models as well, can help reduce the chance of duplication and further establish clear naming conventions.
Great documentation is one of the more overlooked aspects of a great API but cannot be ignored. It is how your API consumer interacts with your API and greatly influences their perception. It is so important, that I will be digging into the specifics in my next post. Here is a brief glimpse into some of the topics I will be covering:
Great APIs don’t just happen. They require a well thought out strategy and design process from step one. Trying to meet these needs in the middle of the design process or post design is a recipe for disaster. Define your audience to meet their needs, choose formats, specifications, and architecture that will persist, maintain consistency and clarity with a style guide, and always provide great documentation (more on that next month).