What Belongs in an API Style Guide

A style guide is not a list of rules. It is a list of decisions, and the rules are how you write them down so that a machine can help.

That distinction decides what goes in. A decision has a reason and a cost, so it survives its first disagreement. A preference has neither, and it becomes the rule everybody learns to ignore.

A rule is a decision with a reason attached

The test for every entry is short. Somebody should be able to say what goes wrong when it is violated.

For a duplicate operation identifier the answer is concrete, because generated clients either fail to compile or silently lose a method. For unique paths the answer is that the second declaration is unreachable. For a missing error response the answer is that every consumer has to discover the failure shape by causing it.

When the honest answer is that this is how we have always done it, the rule will lose its first real argument anyway. In the meantime it costs you credibility for the rules that matter, which is a bad trade for a naming preference.

The subjects a guide has to cover

Seven areas account for nearly every decision two teams would otherwise make differently.

Naming. Path segments, path and query parameters, schema names, property names, enum values and operation identifiers. The value is not tidiness, it is that a reader who has seen three of your endpoints can predict the fourth.

Resources and URL structure. Whether collections are plural, how deep nesting goes, and what happens to actions that are not create, read, update or delete. The resource chapter of the design guide covers the decisions themselves.

Errors. One body shape for every failure across every API, with a machine-readable code that clients can branch on. This is the single highest-value entry in most guides, because it is the one every consumer touches.

Collections. Paging, filtering and sorting, expressed the same way everywhere. Three pagination styles in one organisation means every consumer writes the loop three times.

Headers and metadata. Correlation identifiers, rate limit state, caching validators and deprecation signals. Headers are covered in their own chapter, because they are the part that decays first.

Security. Which schemes are permitted, where credentials may travel, and what an endpoint without a security requirement means. A rule that keeps API keys out of query strings pays for itself the first time somebody reads a server log.

Documentation completeness. What has to be present before an endpoint counts as documented, which is usually a summary, a description, a declared success response and at least one error.

Must, should and may

Not every decision deserves the same force, and a guide that does not say so leaves the question to whoever runs the tool.

A must is something you would revert a release for. There are fewer of these than people expect, and they cluster around things that break downstream rather than things that look untidy.

A should is the house default. Departing from it is allowed and should be visible, which is exactly what a warning is for.

A may is a recommendation you are still socialising, or one that genuinely depends on the API. Writing it down is still worth it, because the next team gets the benefit of the thinking without the obligation.

Mapping those three onto the severities of a tool is a separate decision, and it is the subject of the next chapter but one.

Rules that fit the APIs you already have

The guide is worthless if applying it to your existing estate is impossible, and this is where most first drafts break. Write the rule as a shape with a parameter wherever you can. A rule that checks that path segments follow one convention applies to an API built on camelCase just as well as to one built on kebab-case, and you set the convention once. A rule that hard-codes kebab-case gives a team with three years of /orderItems a choice between renaming forty paths and turning the check off, and they will turn the check off.

Where a rule genuinely cannot fit a particular API, scope the exception rather than weakening the standard. One project that departs from one rule is a documented decision, while a standard lowered for everybody because of one legacy service is a loss you never get back.

What belongs somewhere else

Three kinds of entry look like style guide material and are not.

Anything a person has to judge belongs in a design review, because a rule that needs human interpretation either never fires or fires on everything. Anything the specification already rejects belongs to validation, since re-checking syntax adds findings without adding information. Anything that encodes one person's taste belongs in a conversation, and it will not survive contact with a second opinion.

The style guide post works through the same boundary from the opposite direction, starting from the noise a bloated guide produces.

In Routebase

The built-in rules are grouped into the five categories of naming, completeness, best practices, security and structure, which is close enough to the subject list above to use as a starting outline.

Each rule carries a target, a default severity and, where the convention is genuinely a choice, a dropdown that sets what the rule checks. The URL path rule is the one that matters most in practice, because it accepts kebab-case, camelCase, PascalCase or lowercase, so an existing API keeps the check instead of losing it. Severity is set for the organisation and can be overridden per project, and the project view marks where each value came from.

Rules whose name says must are not automatically errors, since the wording and the severity are set independently. Configuring the guide needs the governance permission held by admins and owners, and it is a Pro plan feature. The Style Guide guide lists every rule with its default.