API governance has a reputation problem. In most organizations where the term appears, it refers to a review process: product teams submit API designs to a platform or architecture committee, which returns feedback weeks later (often "the naming conventions are wrong"). The process adds latency, developers view it as a bottleneck, and the committee gets bypassed whenever a deadline is tight. This version of governance is worse than no governance because it creates the appearance of quality control without the substance, and it consumes platform engineering capacity on reviews that do not scale.
There is a different model — one that encodes standards as automated checks and treats the platform team as tooling providers rather than reviewers. This post is about the operational shape of that model, what it requires technically, and where the genuine hard problems remain even when the automatable parts are automated.
Governance Levels: Automated vs. Human-in-the-Loop
Effective API governance distinguishes between rules that can be checked mechanically and decisions that require human judgment. Conflating the two is the primary reason governance programs become bottlenecks: everything goes through the same human review queue, regardless of whether the question is "does this operation have an operationId?" (a mechanical check) or "should this entity have its own top-level resource or be nested under the parent?" (an architectural judgment that requires context).
Mechanical checks belong in CI, enforced by a Spectral ruleset or equivalent. No PR that introduces a spec change should merge if the lint passes when it should not pass. The platform team's job at this layer is maintaining the ruleset — adding rules as new patterns emerge, tuning severity levels as the team learns what violations actually cause problems downstream. The ruleset is the living API style guide; it is what the platform team enforces without being in the critical path.
Human-in-the-loop reviews should be reserved for: new API surfaces (first exposure of a resource or domain), breaking changes that affect external consumers, and architectural decisions with significant long-term implications (choice of versioning strategy, authentication model, pagination pattern). Everything else should not require a platform team review. The question is not "does this need review?" but "is this a decision that cannot be automated?"
Building the Spectral Ruleset as a Platform Product
A Spectral ruleset is a product. It has a changelog, versioned releases, and consumers (the product teams whose CI pipelines depend on it). Treating it as a product rather than a configuration file changes how you manage it.
The practical implication is that the ruleset lives in a dedicated repository with its own versioning, and product teams pin to a specific ruleset version in their CI workflows. When the platform team adds a new rule, it ships as a minor version bump. When a rule becomes required (elevated from warn to error), it ships as a major version bump with a migration window communicated to teams. Product teams are not surprised by new build failures; they opt into ruleset upgrades on a schedule they control.
# Product team CI — pinned ruleset version
# .spectral.yaml
extends:
- "https://governance.internal/rulesets/[email protected]"
# Local overrides (team-specific, reviewed by platform team)
rules:
# This service uses a legacy date format — waiver granted until 2026-09-01
date-format-iso8601:
severity: warn # overrides ruleset's 'error'The override mechanism is important. A ruleset that allows no exceptions creates incentives to bypass governance entirely. A ruleset that allows overrides with explicit justification (a comment explaining the waiver) creates an audit trail and a forcing function for resolving the underlying issue rather than ignoring it.
Breaking Change Policy: The Highest-Stakes Governance Decision
Breaking change policy is where API governance has the most direct impact on the people consuming your APIs. A poorly communicated breaking change is an outage for your consumers. An overly conservative breaking change policy — never breaking anything, ever — is a technical debt accumulator that constrains API evolution indefinitely.
Most platform teams that have thought carefully about this land on a policy that has three components: a definition of what constitutes a breaking change (must be in writing, cannot be "the platform team decides"), a minimum deprecation period (typically 3-6 months for external APIs), and a communication mechanism that is machine-readable in addition to prose.
The machine-readable component is where governance and tooling intersect. If your deprecation policy requires a Sunset response header on deprecated endpoints (per RFC 8594), and if that header is injected automatically based on the x-sunset-date annotation in the spec, then compliance with the deprecation policy is automatable. The platform team does not need to check that headers are being set correctly; the API gateway that reads the spec does it. The governance policy becomes a Spectral rule and a gateway configuration, not a checklist item on a manual review.
# Spectral rule: enforce breaking change policy
breaking-change-requires-sunset:
description: |
Any operation marked deprecated must carry x-sunset-date
at least 90 days in the future.
given: "$.paths[*][*][?(@.deprecated==true)]"
severity: error
then:
- field: x-sunset-date
function: defined
- field: x-sunset-date
function: schema
functionOptions:
schema:
type: string
format: dateGovernance Metrics That Actually Matter
API governance programs often measure the wrong things: number of reviews completed, number of violations caught, number of teams onboarded to the style guide. These are activity metrics, not outcome metrics.
The outcome metrics that actually indicate whether governance is working: deprecation-to-removal cycle time (how long does it take from a deprecation annotation being added to the consumer migrating off?), spec-to-implementation drift rate (how often do automated contract tests catch spec violations in production?), and time-to-first-integration (how long does it take a new consumer to make their first successful API call?). The last one is partially a developer portal and SDK quality metric, but governance has real impact there: a well-governed spec generates better documentation and better SDKs automatically.
Tracking these metrics requires instrumentation. Deprecation cycle time requires logging when consumers stop calling deprecated endpoints. Spec drift requires running contract tests in production. Time-to-first-integration requires event tracking in the developer portal. None of this is expensive to build, but it requires intentional decisions about what to measure and where to surface the data.
Where Governance Still Requires Humans
We are not saying that all API governance decisions can or should be automated. There is a genuine class of architectural judgment that requires the kind of contextual reasoning that a Spectral rule cannot supply.
The question "should GET /users/{userId}/orders return all orders or just active orders?" depends on the domain model, the access control semantics of the calling context, and the performance characteristics of the underlying data store. None of those are checkable by a linter. The question "should this API use CQRS and expose separate read and write models?" is an architectural decision with significant implications for versioning, SDK design, and consumer mental models. These decisions benefit from a human review with appropriate context — not because "governance" requires it, but because the decision genuinely benefits from a second perspective.
The platform team's role in these reviews is to ask the right questions, not to gatekeep. The question is not "does this match the standard pattern?" but "what are the tradeoffs you are making here, and are you making them intentionally?" That kind of review adds value. The review that flags naming convention violations that a Spectral rule should have caught first does not.
Apistaq's Approach: Governance as Platform Capability
The tooling layer that Apistaq provides is designed around this model: governance rules are encoded in the spec lifecycle rather than managed as a separate process. Rate limit policies expressed as OpenAPI extensions get enforced at the gateway level without a manual configuration step. Deprecation annotations trigger automated sunset headers and portal UI changes without a platform team intervention. Breaking change detection runs in CI before any spec change can merge.
The platform team's attention gets redirected from mechanical compliance checking to the work that actually requires judgment: reviewing new API surfaces, setting the policies in the Spectral ruleset, and monitoring the governance metrics that indicate whether the standards are actually working. That is a more valuable use of platform engineering capacity than reviewing whether every operation has an operationId.
