API Style Guides and Consistency — REST APIs in Depth

Q: What's a 'custom method' in Google's AIP style?

An action that doesn't fit standard CRUD, expressed as `POST /resources/{id}:verb` (e.g., `:cancel`, `:batchCreate`).

At scale, consistency comes from a written style guide plus automation. Start from a public one — Google AIPs, Microsoft REST API Guidelines, Zalando RESTful API Guidelines — and adapt: naming and casing, IDs, pagination, filtering, errors, versioning, dates and money, auth, and deprecation. Encode rules in Spectral rulesets that lint OpenAPI specs in CI, and run lightweight API design reviews for new surfaces.

Major public API style guides

Topic	Google AIP	Microsoft	Zalando
Style	Resource-oriented, custom methods (:verb)	REST + OData influence	REST, strong JSON rules
Pagination	page_token / next_page_token	nextLink	Cursor-based
Errors	google.rpc.Status	error object	Problem JSON (RFC 9457)
Versioning	Major version in path (v1)	api-version query param	Avoid; compatible evolution, media types
Long-running ops	Operation resources	Operation-Location header	202 + status

# .spectral.yaml (excerpt)
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    given: "$.paths[*]~"
    then: { function: pattern, functionOptions: { match: "^(/[a-z0-9-{}:]+)+$" } }
  problem-json-errors:
    given: "$.paths[*][*].responses[?(@property >= 400)].content"
    then: { field: "application/problem+json", function: truthy }

Common pitfalls

A style guide nobody enforces.
Rules that change per team.
Reviews that bikeshed naming but miss security and compatibility.

Key points

Adopt and adapt a public guide
Lint specs with Spectral in CI
Design reviews for new APIs

Further reading: Zalando RESTful API Guidelines

Practice questions

How do you keep 30 teams' APIs consistent?

Answer

A shared style guide, a linting ruleset (Spectral) enforced in CI on every OpenAPI change, shared libraries for errors/pagination, and lightweight design reviews.

What's a 'custom method' in Google's AIP style?

Answer

An action that doesn't fit standard CRUD, expressed as POST /resources/{id}:verb (e.g., :cancel, :batchCreate).