Public style guides are available for Professional and Enterprise workspaces. Simply log into your workspace, click on the Governance tab, and look for Public Style Guides, then enable the rules you want to use.
Inconsistency is one of the fundamental reasons for a sub-par developer experience for APIs. Inconsistent APIs across an API platform frustrate and confuse developers both internally and externally. This leads to reduced adoption, increased time to value, and a lack of trust. It is essential to keep the design of an API consistent — to make it a predictable experience.
Consistency is Hard
Ask 100 developers where a semicolon should go, and you’ll probably get 100 different answers. Now, with organizations building dozens of APIs across multiple teams, business domains, and potentially multiple geographic locations, the problem gets even worse.
So, how do you build consistent APIs? Organizations with large API programs like Google, Microsoft, and Cisco publish API guidelines that usually span multiple pages. Also known as “API Design Guides” or “API Standards,” the concept of “make a bunch of decisions and write them down” has helped API teams for decades. These guidelines might contain rules about how to handle versioning, filtering, error formats, naming conventions, pagination, or any of a million other variable parts of an API, which different teams would likely make different decisions on.
Google’s publicly available API design guidelines
Let developers focus on what’s important
Developers prefer focusing on designing and implementing the capabilities rather than going back and forth to read long documentation on best practices and guidelines. Even if they do, this makes conformance hard and delivery slow.
Imagine asking developers to write Javascript without ESLint. I mean, they can, but they would certainly not want to. Linters like ESLint bring syntax issues and styling conventions out of large PDF documents into developer environments, giving real-time feedback while code is being written. This has drastically improved the quality of code and made code reviews faster.
If your Pull Request has no typos or unused variables and is compliant with the style guide, the conversation tends to focus on the architectural point of view. Developers don’t need to get in that single or double quotes or tab vs. spaces discussion. It is a productivity gain at the least.
API design guidelines are similar. They are fundamental to a robust and high-quality API program, but when written in long pages of text, It rarely produces the expected results.
What’s the answer? Bring these API guidelines to design environments.
Realtime OpenAPI linting in Stoplight Studio
Create a Style Guide
API specification linters like Spectral provide a way to standardize these guidelines into automated rules that can then be used to detect design issues – basically ESLint for API designs. They are context-aware, providing real-time feedback within an API design environment like Stoplight Studio, VS Code, and JetBrains IDEs as APIs are being designed. Style guide rules can range across guidelines like naming conventions, documentation best practices, error handling, pagination patterns, opinionated design nudges, etc. We’ll be covering examples of different rules in follow-up blogs in the Style Guides Rulebook Series.
These style rules can be created in an easy-to-understand JSON/YAML format or using Stoplight Studio.
Style guides in JSON/YAML
Style guides in Stoplight Studio
Lint API specifications within the design environment
Once created, these style guides should be added to each API design project. Overrides can be used to ignore rules that might not apply to legacy APIs or particular domains. Linting against these style guides should be done while designing APIs to promote conformance and quick fixes.
Realtime OpenAPI linting in Stoplight Studio
Realtime OpenAPI linting in VS Code
Realtime OpenAPI linting in JetBrains IDEs
Run design checks within your CI
Much like code linters, it’s a good idea to run these checks within your CI against each pull request for a new API design.
Spectral comes with a GitHub action to do this easily for CI pipelines within GitHub.
Linting within CI pipelines
Gather feedback and iterate on design guidelines
If you are starting with your API program, starting with a core set of design guidelines helps you stay consistent from the onset. If your API program is already mature, it’s good to start trying to tame the beast. After all, good developer experience is fundamental to success for your API program, and Style guides are a powerful tool to take a step in the right direction.
Like any set of guidelines, agreement among stakeholders is important for its success. Start with a core set that everybody can agree on, add and iterate as you get feedback.
Stay tuned for more additions to the Style Guide Rulebook series in the coming weeks, but in the meantime, check out our new Shared Style Guides feature or our open-source linting tool, Spectral for yourself.
