Creating API style guides can bring consistency across your API program, but coming up with rules and best practices can be a daunting task. Some of the hardest questions are:
- What kind of rules should we include in a Style Guide? Security, Casing, OpenAPI best practices e.t.c
- What should be an error vs what should just be a warning?
- How to document a style guide to make it easier for designers to fix issues? i.e. Including valid and invalid examples e.t.c.
As part of this Style Guide Rulebook series, we have been going through popular style guides in the industry to share common rules and patterns to get started with. What we’ve seen is that starting with a company-wide API Style guide is one of the hardest tasks to take up and is one of the biggest reasons why a lot of API programs still operate without a Style Guide (Please don’t!).
To make this easier we have taken up the task of creating and sharing Public Style Guides that gather rules from top companies around themes like Security and Design, use best practices while documenting and creating those rules, and share them in the Stoplight Platform so that users can start with them in a single click. These style guides can act as a starting point for a company-wide style guide or be used for ideas around adding new rules to existing style guides.
In the first iteration, we started with these two public sets of rules:
URL Style Guidelines
REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client. A resource has an identifier, which is a URL that uniquely identifies that resource.
This Style Guide covers best practices, naming conventions, and parameter conventions to help build consistent and robust URLs.
Check it out here.
Enforce HTTPS
We all agree that HTTPS should always be used, but it is an easy one to miss. Enforcing this style guide would ensure that developers/designers don’t miss out on this basic but important convention.
Check it out here
This is just the start, and we’ll be releasing style guides consistently over the next few months that cover popular themes and standards. Some that we are considering putting out next are the following:
- Documentation Best Practices
- Security Best Practices
- OWASP Top 10
- JSON:API
- Zalando Restful Guidelines
- Amazon AWS Gateway Best Practices
If you’re interested in these or have thoughts on some other style guides that we should create, leave an insight here on our product roadmap!
