Guidelines

To access the complete Monite API Style Guide, please see Guidelines.

Purpose

As an API-First company, we put extremely high expectations on the quality of our APIs. That's why we need to have solid guidance on how we should build our APIs, how they should behave, and why we are making certain choices around our APIs.

Although there are already a lot of good APIs and knowledge around building APIs in the industry, there is no single standard way of building Web APIs. This means that every company needs to make their own choices on what makes their API good, and we are not an exception to that.

Our API Style Guide is a representation of our choices, and we want to keep it public to share our knowledge with our customers and anyone else who is interested in building modern Web APIs.

Scope

This style guide should be applied by our development teams to both public/partner and internal APIs. The main reasons for that:

The fewer differences we have between our internal and public API layers, the easier it will be for us to develop our platform.
Any API, even if it's internal at the moment, might be tasked to become public in the future. With this mindset we should build all our APIs externalizable from the beginning, so having a shared style guide will help us avoid unnecessary changes in the future.

Target audiences

Most of these guidelines are focused on technical aspects of API design and implementation, and therefore are points of interest mostly for software developers.

However, there are certain aspects of these guidelines that are addressing more common issues and should be valuable for a broader group, including product managers, technical writers, technical support, developer experience engineers, and people in many other roles.

Spectral

We believe that nobody can remember all the rules in the API style, so it's key to be able to automatically validate as many rules as possible.

For that purpose we are using Spectral that can lint API contracts in the OpenAPI format.

To start with Spectral, you can install it as an npm package or use other installation methods:

npm install -g @stoplight/spectral-cli

Additionally, you might want to install a spellchecker package to check spelling of API names and descriptions:

npm install spellchecker

After that, you are ready to validate your OpenAPI file with the rulesets in this repository:

spectral lint spectral/test-openapi.yaml -r spectral/monite.all.yaml

For more detailed guidance on how to automate your style guide, see Spectral.

Contributing

We encourage everybody to contribute to this API Style Guide. Only together we can achieve high quality and clarity of all the guidelines, as well as keep them up-to-date and useful for the API community.

It doesn't matter whether your official job title is an engineer or not - if you have some feedback and want to make this style guide better, please share with us.

You can contribute in the following ways:

Create an issue (if you spotted a problem but not sure how to solve it best).
Create a merge request (if you have a good idea on how we should change our style guide).
Star, fork, and share the link to this repository with your network.

See also

There are a lot of other resources created and shared by some companies and API enthusiasts. In some of our work, we were relying on these resources; while others are listed here just to help you build the bigger picture.

The list below is not the most comprehensive list of other API style guides, but can give you good insights on where else you can look for inspiration.

License

philsturgeon/api-style-guide

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages