2.0 KiB
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[]=yor?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
errorsextension 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) andpage-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.