A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: "Ninety-Five Companies Publish Their API Design Rules, And APIs.io Lists Them First," Kin Lane, October 12, 2026, https://apievangelist.com/2026/10/12/ninety-five-companies-publish-their-api-design-rules-and-apis-io-lists-them-first/
Owen ran the linting for a platform team of forty engineers. Their Spectral ruleset had sixty-odd rules, a decade of arguments compressed into YAML, and it had never left the private repo.
The post opened with the question he had never thought to ask about his own work: "who actually publishes the rules their APIs are designed to?" Not who has a style guide in a wiki, it said, and not who lints in CI behind the firewall. Who serves it where anyone can read it and puts their name on it.
The answer was 95 providers out of 28,834 in the catalog. A third of one percent. The post said the companies running a ruleset internally are a much larger group than the companies willing to show it. Owen was in the larger group.
He kept reading for the list. Almost all of what was published lived on GitHub, usually a .spectral.yaml next to the OpenAPI. The biggest rulesets came from governments and regulated companies: Italian and Dutch public bodies, a Norwegian transit authority, banks. The private companies mostly sat between three and thirty rules.
The detail that stayed with him was the 37 published rulesets showing zero rules of their own. That was not laziness, the post said. PayPal extends spectral:oas and turns four checks down to warnings. Others extend IBM Cloud's ruleset or a national API profile and switch off what does not fit. Extend a shared standard and tune it, rather than copy it.
Owen opened his ruleset. Twenty of his sixty rules were copies of the defaults with the wording changed. He could delete them and extend instead.
He made two tickets. One to slim the ruleset down to what was actually theirs. The second, which he knew would take a meeting, to publish it next to their OpenAPI. If governments could show their rules, he could not think of a good reason his team couldn't.