What Belongs in an API Style Guide

Someone adds a rule: paths must be kebab-case. It is a good rule. Two days later the build is red on an API that has shipped /orderItems for three years, and the only change that would make it green renames forty-one paths and breaks every consumer at once.

Both sides of that argument are right, which is exactly what makes it a bad fight to have in a pull request. The rule is correct. The cost of applying it to this API is also correct. What is missing is the thing a style guide is supposed to provide: a decision, made once and written down, about which of those two facts wins here.

Most guides never make that decision. They collect rules instead, because collecting is easy and deciding is not.

Rules are the cheap part

Routebase ships 57 built-in rules across six categories — naming, completeness, best practice, security, structural, and versioning. Writing that list was the least interesting work in the whole feature. Any team can produce fifty rules in an afternoon; the OpenAPI specification alone suggests most of them, and the rest are one argument about plurals away.

What the list cannot tell you is what should happen when a rule fires. And that is the entire question, because a finding that does not change anyone's behaviour is not governance. It is noise with a line number.

Three kinds of finding, wearing the same badge

Run any linter over a real spec and the output arrives as one flat list. It is not one kind of thing.

Something is broken. A $ref points at a component that does not exist. A path declares {orderId} and no parameter defines it. An example does not validate against the schema it illustrates. These are not opinions. The document is wrong, tooling downstream will fail on it, and nobody will defend it in review.

Something is inconsistent. Half the paths are kebab-case and half are camelCase. Two operations share an operationId. The document works; it is merely irregular, and the irregularity costs the next reader a moment each time.

Something is a preference. Whether every operation carries a license block, whether tags need descriptions, whether error responses are enumerated per-operation or once at the top. Reasonable teams differ, and the API is perfectly usable either way.

Only the first kind has an obvious answer. A dangling $ref should stop a build. A missing license block should not — and if your guide treats them the same, you have not built a standard, you have built a wall of red.

The severity is where the thinking goes

Every rule in Routebase sits at one of four levels: Off, Info, Warning, or Error. Choosing among them is the real work, and the useful question is not "is this rule good?" but "what do I want to happen at three in the afternoon when this fires on someone else's pull request?"

Error means stop. Reserve it for the broken class, plus the handful of security rules where the cost of shipping is genuinely worse than the cost of blocking — an API key accepted in a query parameter, a server URL still on plain HTTP.
Warning means fix it when you are here anyway. Most naming and completeness rules belong here for their whole life, and that is not a failure state.
Info means the guide has an opinion and is not going to insist. Useful for rules you are still socialising.
Off means you looked at it and decided no.

That last one deserves defending, because switching a rule off feels like losing. It is the opposite. An enabled rule that everyone has learned to scroll past is worse than a disabled one: it costs the same attention on every run and buys nothing, and it teaches the team that findings are background texture. A guide of fifteen rules that people act on beats a guide of fifty-seven that people mute.

A dashboard where every lamp is lit tells you nothing — the one warning that matters arrives in the same colour as eleven you have already learned to ignore. Turning the other eleven off is what makes the twelfth mean something.

Where a rule lives matters as much as what it says

The kebab-case fight at the top has a real answer, and it is not "give up" or "rename forty-one paths".

In Routebase, severity is set per rule at the organisation level and can be overridden per project, with a reset that drops the project back to inheriting. So the house standard stays Warning for every new API your team designs, and the one legacy service that will never be renamed sets that single rule to Off in its own project. Nobody argues in a pull request, because the argument already happened once, in the place where it belonged.

Treat the override as the feature it is, not as a loophole. A guide with no escape hatch does not produce compliant APIs; it produces teams that stop running the guide. The escape hatch is why the other fifty-six rules still apply to that legacy service.

What does not belong in a style guide

Three things, reliably:

Anything without a machine-checkable condition. "Endpoints should be intuitive" is good advice and a bad rule. If a person has to judge it, it belongs in a review, a design document, or a conversation — not in a linter that will either never fire or fire on everything.

Anything nobody can justify. For each rule, someone should be able to say what goes wrong when it is violated. If the honest answer is "that is how we have always done it", the rule will not survive its first real disagreement anyway, and it will cost you credibility for the rules that matter in the meantime.

Anything that duplicates the specification. OpenAPI already rejects a malformed document. A style guide that re-litigates syntax adds findings without adding information.

Where a rule is checkable but specific to your house — an internal header that must appear on every operation, a naming prefix your platform requires — custom rules are declarative rather than scripted: a target, a condition type, the field it applies to, and the value to compare against. That constraint is deliberate. A rule you can read at a glance is a rule the next person can change without archaeology.

Start with the spec you already have

The worst time to write a style guide is on an empty page, because everything seems reasonable in the abstract and you will enable all of it.

Run a draft guide against an API you already shipped instead. The output is your actual agenda: every finding is either something you genuinely want fixed, something you want noted, or something you now know to switch off. Sorting that list once is a couple of hours, and it produces a guide calibrated against reality rather than against a blog post — including this one.

That sorting is also where a style guide stops being a document and becomes part of the workflow. It is worth checking where the guide runs in your toolchain: a linter that only exists on someone's laptop enforces nothing, and one that runs in the same place your specs are designed, reviewed and published gets to catch things before the pull request rather than after. If you are weighing that up, our comparison with Stoplight lays out where the style guide sits when linting is one stage of the lifecycle rather than the whole product.

None of this makes the kebab-case argument disappear. It just makes it happen once, in the open, at organisation level — instead of every time somebody opens a pull request against the wrong service. That is all a style guide really buys you, and it is worth a great deal more than the rule count on the front of it.