Files
claude-config/principles/rest-apis.md
T

2.0 KiB

REST APIs

Applies to every REST API we build, regardless of product or stack. Existing APIs keep their current shapes until their next major version — reviewers flag deviations on new surfaces, not old ones.

URLs & query parameters

  • URL paths and parameter names may only contain the characters a-z, 0-9, - and / (kebab-case); parameter values are exempt. E.g.: /fooBar?WakkBazz=Value! should be /foo-bar?wakk-bazz=Value!.
  • Query parameters that can be more than one are repeated flat keys: ?ids=x&ids=y. Do not do ?ids[]=x&ids[]=y or ?ids=x,y. Where a framework's default parsing collapses repeated keys, parse them with one shared helper per stack — never reimplement per endpoint.

Errors

  • Error responses follow RFC 9457 (application/problem+json): type, title, status, detail.
  • Field-level validation errors go in an errors extension member (RFC 9457 §3.2), one entry per field with the field name exactly as the consumer sent it and an actionable message.
  • Details must be actionable for the consumer and never leak internals (stack traces, table names, upstream URLs, ticket ids).

Status codes

  • Follow the HTTP standard (RFC 9110); no local reinterpretations.
  • An idempotent PUT returns 201 when it created the resource, 200 when it updated it.
  • When an upstream dependency fails, report it honestly (502/503) — never disguise it as a local 500.

Pagination

  • Offset-based by default: page (default 1) and page-size. Counts and navigation links live in the response body (meta/links), not in headers.

Versioning

  • Major version as a URL path prefix (/v1/...). Breaking changes ship as a new major version, never in place. No header- or per-endpoint versioning.

OpenAPI

  • Every REST API has a well-written OpenAPI specification with a live web GUI to view it (e.g. Swagger UI).
  • Ideal: spec first — code generated from the spec. Generating the spec from code annotations is the accepted second best where spec-first isn't in place yet.