Creating API style guides is very useful for bringing 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 it in the Stoplight Platform so that users can start with them in a single click. These style guides can be act as a starting point for a company-wide style guide or used for ideas around adding new rules to existing style guides.

In the first iteration, we have started with these two public set 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.

example

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.

oas2 example

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! 

Peek-a-Boo (1)

Subscribe for the latest in API Design

By submitting this you will be receiving our latest updates on post.

Take a Listen to API Intersection

The podcast on the intersection between API design & digital transformation
Listen

Related Posts