Skip to main content

API Governance: Ownership, Standards, Review Process

What This Concept Is​

API governance is the set of practices that keep an organization's APIs consistent and safe to evolve as headcount grows past the point where everyone knows everyone else. It has three pieces:

  • Ownership: each API has a named team accountable for design, operations, breaking changes, and deprecation. One throat to choke.
  • Standards: a written style guide declaring the house rules - naming, casing, pagination, errors, versioning, auth. Every API in the org is expected to follow it. Deviations require a written exception.
  • Review process: a repeatable way to evaluate a new or changed contract against the standards before it ships.

Governance is not bureaucracy for its own sake. It is the mechanism that prevents 50 microservices from inventing 50 pagination schemes. Geewax frames this as: predictability is a feature; predictability across an entire surface requires governance.

Why It Matters Here​

Small teams can enforce consistency by talking. Large organizations cannot. The moment you have more than one team shipping public-facing APIs, you need either:

  • governance (explicit standards, explicit reviewers), or
  • inconsistency (every team reinvents).

Consumers experience the full surface. A consumer integrating with OrderService, PaymentService, and FulfillmentService sees three different error shapes, three pagination models, and three auth flows. The cost is real and paid externally.

Governance is also what lets you introduce a module-wide change safely: "all APIs must now include a trace_id header" is only enforceable if someone owns "all APIs."

Concrete Example​

A lightweight governance setup used by a mid-sized org:

  1. API Style Guide (library/raw/api-style-guide.md):
    • naming: snake_case field names, plural resource URLs, /v1/ URL prefix
    • errors: RFC 7807 application/problem+json with stable code
    • pagination: page_token/page_size, cursor-based, no offset
    • timestamps: RFC 3339 in UTC, field name *_at
    • money: integer minor units + explicit currency code
    • versioning: URL-path v1/v2; breaking change requires new major
    • deprecation: Deprecation and Sunset headers, minimum 6-month runway
  2. API Review Council: two senior engineers + one DX representative. Meets weekly. Reviews specs, not code.
  3. Review triggers: (a) new public API, (b) new endpoint on public API, (c) any change that changes the wire format, (d) deprecation announcement.
  4. Machine-enforced rules: Spectral linter (.spectral.yaml) in CI. Fails the build on naming violations, missing examples, missing error responses.

Example Spectral rule:

rules:
  example-money-minor-units:
    description: Money fields must use minor units (integer)
    severity: error
    given: $..properties[?(@property.match(/(amount|price|total|fee)/))]
    then:
      field: type
      function: pattern
      functionOptions: { match: "^integer$" }

This lets the Council focus on judgment calls (is this resource modeled correctly?) while the linter catches mechanical violations.

Ownership is written next to the API:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.4.0
  x-owner:
    team: orders-platform
    slack: "#orders-platform"
    pager: orders-platform-oncall

If something breaks, the on-call team is named in the spec itself.

Common Confusion / Misconception​

"Governance slows us down." Inconsistent APIs slow down every consumer, forever. A 30-minute review before shipping a new endpoint is far cheaper than a 6-month migration later.

"We already have code review." Code review catches bugs. API review catches contract mistakes - the things you cannot undo without breaking consumers. They are different checks with different reviewers.

"The style guide is aspirational." If it is not enforced by either a reviewer or a linter, it is not a style guide - it is a wishlist. Pick enforceable rules and enforce them.

How To Use It​

For a team or org introducing governance for the first time:

  1. Pick three to five cross-cutting rules (error format, pagination, casing, versioning, auth).
  2. Write them down in one page. Call it the style guide.
  3. Nominate reviewers. Publish the review trigger list.
  4. Add one linter rule per style-guide rule where possible.
  5. Write a one-page exception template: "we are deviating from X because Y, and the cost is Z."
  6. Re-review the rules quarterly - dead rules rot governance.

Reviewing one API at a time is fine. Reviewing every API in one sprint is how governance projects die.

Check Yourself​

  1. Your org has three teams building APIs independently. What is the cheapest governance step that reduces the worst form of inconsistency?
  2. Why should the API style guide be machine-enforceable where possible rather than just documented?
  3. A team wants an exception to the pagination rule because their data is naturally offset-addressable. Approve, deny, or modify - and why?

Mini Drill or Application​

Write the first draft of an API style guide for a hypothetical 10-team organization. Include, at minimum:

  • naming conventions (case, pluralization, URL structure)
  • error format (name the RFC if applicable)
  • pagination (one scheme, with reasoning)
  • versioning (one strategy, with reasoning)
  • required metadata (trace_id, owner, deprecation headers)

Constrain yourself to one page. Shorter is better - a guide that nobody reads protects nobody.

Read This Only If Stuck​