The Governance Gap: Why API Providers Are Still Hesitant to Open Their Rulebooks

In the rapidly expanding universe of the programmable web, the question of "how" an API should behave has long been shrouded in corporate secrecy. While thousands of organizations utilize sophisticated linting tools and internal style guides to maintain consistency, these governance artifacts rarely see the light of day. Today, a new initiative from APIs.io seeks to dismantle this wall of silence. With the launch of a dedicated Rules section, the platform is finally providing a definitive answer to a question that has haunted the developer relations community for years: Who actually publishes the design rules their APIs are built upon?

The answer, as it turns out, is a humbling reality check for the industry. Out of 28,834 API providers indexed in the APIs.io catalog, a mere 95 have made their Spectral rulesets publicly accessible and attributed to their brand. That represents approximately one-third of one percent of the catalog—a startlingly low figure that highlights a significant gap between internal engineering standards and public-facing transparency.

The Taxonomy of Governance: Understanding the Landscape

To make sense of this data, APIs.io has categorized the 6,192 rulesets currently in its catalog. By establishing clear provenance, the platform distinguishes between intentional, provider-led governance and automated or inferred observations.

The Four Tiers of Ruleset Provenance

Published by the Provider: The "gold standard." These are rulesets written, maintained, and served by the provider, reflecting an explicit commitment to their own design standards.
Derived from Contracts: These rules are generated by analyzing existing OpenAPI definitions to identify recurring patterns. They represent what a provider is doing, not necessarily what they intend to enforce.
Generated by API Evangelist: These are automated starting points created by tooling to help providers bootstrap their governance journey. They are suggestions, not official policy.
Unrecorded Authorship: Legacy data points created before the platform’s current provenance tracking was implemented.

The objective of this categorization is to move beyond mere volume and toward a nuanced understanding of "Contract Governance." As the industry pushes for better interoperability, knowing whether a rule is an intentional mandate or a statistical observation is critical.

A Chronology of the "Rules" Project

The journey toward this level of transparency has been a multi-year effort. For years, the API Evangelist team attempted to quantify governance through the "Kin Score," a rubric designed to measure the maturity of API programs.

Early Stages: The Kin Score initially focused on documentation, security, and lifecycle management. Governance remained an abstract concept, often impossible to verify without insider access.
The Rise of Spectral: As the industry converged on Spectral as the de facto standard for linting OpenAPI and AsyncAPI files, the opportunity to index these rulesets became a reality.
The 0.23 London Release: This update to the Kin Score introduced formal points for publishing rulesets, setting the stage for more granular tracking.
The 0.24 Stockholm Release (October 13th): This milestone finalized the grading logic. By reclassifying unmarked rulesets as "derived" rather than "provider-authored," the platform has forced a clearer distinction between intent and incidental discovery.

This evolution represents a shift from passive observation to active governance. The project has moved from simply counting APIs to evaluating the quality of their blueprints.

Supporting Data: What the 95 Are Actually Doing

When we examine the 95 providers that have stepped forward to publish their rules, a fascinating picture emerges. The data suggests that for most, the "ruleset" is still an experimental, evolving artifact.

The GitHub Dependency

The decentralization of API governance is evident in the hosting choices. Of the 108 rulesets captured, 104 are hosted on GitHub, typically as a .spectral.yaml file within the repository containing the API’s OpenAPI specification. Only four providers serve their rules from their own domains. This indicates that for most developers, governance is currently treated as an extension of the development workflow rather than a first-class citizen of the developer portal.

The Philosophy of Inheritance

A striking trend is that many organizations are choosing to "extend" rather than "invent." Roughly one-third of the providers in the published group do not write a single original rule from scratch. Instead, they extend standard profiles like spectral:oas or IBM’s published rulesets, turning specific checks into warnings or toggling them off to suit their specific infrastructure. This is widely considered the superior engineering path, as it fosters the growth of a shared ecosystem of standards.

The Heavyweights of Governance

The most robust rulesets come from the public and regulated sectors. Organizations like AgID (Italy), Entur (Norway), and the Sovereign European Cloud API are leading the way, with rulesets containing 40 to 80+ specific constraints. Private sector players, such as Adidas, Camunda, and BitGo, typically land in the 3–30 rule range. These rules cover essential territory: ensuring HTTPS enforcement, standardizing casing (camelCase), and prohibiting the use of verbs in path names.

Official Responses and Industry Implications

The implications for the wider developer community are significant. By making these rulesets discoverable, APIs.io is enabling a "copy-and-improve" culture. Smaller organizations no longer need to build a governance strategy from a blank page; they can adopt the standards of established entities like Adidas or the Norwegian government, adapting them to their own needs.

However, the "error vs. warning" debate remains a point of contention. Of the 71 providers that define their own rules, 18 rely exclusively on "error" severity, effectively creating a "my way or the highway" environment. This approach often fails to guide developers through the nuances of API evolution. In contrast, leaders like Adidas utilize a tiered approach, using "errors" for mandatory security and structure, and "warnings" for best practices—a balance that the Kin Score explicitly rewards.

The Future: A Call to Action

The publication of this data serves as a challenge to the remaining 28,000+ API providers. If a company runs a ruleset in their CI/CD pipeline—and most mature engineering teams do—the work is already done. The artifact exists. By simply exposing that file to the public, organizations can earn significant points in the Kin Score, but more importantly, they can offer their consumers a clearer map of what to expect.

As the industry matures, the "Governance Gap" will likely close. We are moving toward a world where an API’s quality is not just measured by its documentation or its uptime, but by the transparency of its design constraints.

For those looking to join the 95:

Stop Copying, Start Extending: Leverage standard rulesets and override only what is necessary.
Use Balanced Severities: Don’t just forbid; guide. Utilize warn and info to help developers grow alongside your API.
Make It Visible: Treat your .spectral.yaml as part of your public developer experience.

The era of "secret" API governance is coming to an end. The tools are ready, the catalog is open, and the standard has been set. The question remains: is your organization ready to put its name on its rules?