Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Design-first Workflows

API Style Guides and Governance with OpenAPI

Write an API style guide that your OpenAPI lint rules can enforce: naming, plural nouns, pagination, problem details errors, review process, with a runnable style checker.

When one team writes one API, taste is enough. When ten teams write fifty APIs, taste produces fifty dialects: userId here, user_id there, errors as plain strings in one service and JSON objects in another. API governance is the set of habits and tools that keep many APIs consistent. Its main tools are a written style guide, automated lint rules and a lightweight review process.

This lesson shows what to put in a style guide and how an OpenAPI document lets you enforce it automatically. The linting tools mentioned (Spectral, Redocly CLI) are real but cannot run on this site; the Python checkers are stand-ins.

What goes into a style guide

Keep the guide short and concrete. Each rule should be something a machine can check or a reviewer can point at.

Area Example rule
Paths Lowercase, kebab-case, plural nouns for collections: /book-orders, not /getOrders
Methods GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes; never change data with GET
Properties One case across the API (for example camelCase), ISO 8601 for dates, ISO 4217 for currency codes
IDs Opaque strings, never reused
Pagination The same parameters everywhere (limit and cursor, or page and pageSize) and a standard response envelope
Errors One shape, for instance RFC 9457 application/problem+json
Status codes 201 with Location on create, 204 for empty success, 409 for conflicts, 422 for validation
Security Every operation lists security, or is explicitly marked public
Versioning How versions appear and how breaking changes are announced

Errors as a shared contract

RFC 9457 (which replaced RFC 7807) defines "problem details": a JSON object with type, title, status, detail and instance, plus any extension fields you need. Describe it once in components and reuse it:

YAML
components:
  schemas:
    Problem:
      type: object
      required: [title, status]
      properties:
        type: {type: string, format: uri}
        title: {type: string}
        status: {type: integer}
        detail: {type: string}
        instance: {type: string}
  responses:
    NotFound:
      description: The resource does not exist.
      content:
        application/problem+json:
          schema: {$ref: "#/components/schemas/Problem"}

Every operation then points to #/components/responses/NotFound instead of inventing its own shape. The builder below produces a problem object the same way across services.

Python Stand-in: one error shape everywhere

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Make rules checkable

A style rule nobody enforces becomes a suggestion. Turn each rule into a lint rule. The next stand-in checks a spec for four of the rules above: kebab-case plural paths, no verbs in paths, camelCase properties and a declared security on every operation.

Python Stand-in: a style-guide checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

(The empty security: [] on /book_reviews/{reviewId} counts as an explicit "public" declaration, which the guide allows; a missing key does not.)

Governance without bureaucracy

flowchart TB
  G["Style guide<br/>short, versioned"] --> R["Shared lint ruleset<br/>published as a package"]
  R --> E["Editor feedback"]
  R --> C["CI gate on every PR"]
  C --> V["Design review for new APIs<br/>and breaking changes"]
  V --> P["Publish to API catalog"]

Automation handles the boring checks so that reviews can focus on design.

Practical tips:

  • Publish the ruleset as an npm package or a URL and extends it everywhere.
  • Start with warnings, promote to errors as teams catch up.
  • Use overrides for legacy APIs and set expiry dates on them.
  • Keep an API catalog (a page or tool listing every API, its owner, spec and docs link).
  • Review new APIs and breaking changes by humans; let the linter handle the rest.
  • Version the style guide itself and write down why each rule exists.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What is RFC 9457 used for in an API style guide?

    RFC 9457 (which obsoletes RFC 7807) defines application/problem+json with type, title, status, detail and instance.
  2. 2. Why convert style rules into lint rules?

    Unenforced rules decay. Automation applies them consistently with no reviewer effort.
  3. 3. Which is a good path under typical REST style guides?

    Plural lowercase nouns for collections; the HTTP method carries the verb.

Summary

  • A style guide lists concrete rules for paths, methods, properties, pagination, errors, security and versioning.
  • Define shared pieces such as problem details once in components and reuse them.
  • Turn rules into lint rules and run them in the editor and CI.
  • Keep human review for new APIs and breaking changes; keep a catalog.
  • The Python checkers are stand-ins for lint-rule logic.

Next: Versioning and breaking changes