API Design Conventions

Overview

Most backend-caused QA bounces are inconsistency, not bugs: a 422 here and a 400 there, an unbounded list, a create that isn't safe to retry. This skill is the shared vocabulary so every endpoint in a service answers these the same way.

Core principle: the repository's existing choice wins (rule repo-conventions-win); these are the defaults for a new repo or an endpoint with nothing established yet.

One error shape

Default for a repo with no convention yet: RFC 9457 application/problem+json — {type, title, status, detail, instance} plus an extension array for field errors, e.g. errors: [{field, message}]. Never a bare string, never a stack trace, never a raw framework exception body. Map it in ONE place (fiber-rest-api's central ErrorHandler, Spring @RestControllerAdvice + ProblemDetail/spring.mvc.problemdetails.enabled=true, Quarkus @ServerExceptionMapper) — not per handler.

Status code table

Code	When	Note
200 / 201	success / created	201 includes Location of the new resource
204	success with no body (e.g. delete)
400	unparseable or invalid input	or 422 if the repo already standardizes on it — don't introduce a second convention
401 / 403	unauthenticated / forbidden
404	missing, OR present-but-not-yours (BOLA, api-security-checklist)
409	duplicate or invalid state transition	e.g. a unique-constraint violation (pgx 23505)
412	a conditional request's precondition failed	If-Match version mismatch
413	body too large
429	rate-limited	include Retry-After
500	genuinely unexpected only	never for validation or not-found

The task's acceptance criteria or an existing contract always wins over this table.

Mapping database errors (Go, pgx)

Do the translation in the adapter, never in the handler:

switch {
case errors.Is(err, pgx.ErrNoRows):
    return domain.ErrNotFound
case isPGCode(err, "23505"):          // unique_violation
    return domain.ErrConflict
case isPGCode(err, "23503"):          // foreign_key_violation
    return domain.ErrInvalidReference
}

Pagination

• Every list endpoint has a default page size (e.g. 20–50) and a enforced maximum (e.g. 100) — clamp silently or reject with 400, whichever the repo already does.
• Deterministic order: ORDER BY created_at DESC, id DESC (a tiebreaker column prevents duplicate/missing rows across pages when timestamps collide).
• Prefer keyset pagination over offset for anything that can grow past a few thousand rows: WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT $3+1, use the extra row to compute has_more, return an opaque next_cursor (base64 of the last row's sort key). Offset pagination (LIMIT/OFFSET) is fine for small, bounded tables only.

Idempotency and concurrency

• PUT and DELETE are idempotent by construction — calling them twice with the same input produces the same end state.
• Make POST/create idempotent where duplicates are a real risk: a natural unique key with INSERT ... ON CONFLICT (key) DO NOTHING RETURNING ..., or an Idempotency-Key request header backed by a dedupe table, following the draft semantics: same key + same payload → replay the stored response; same key + different payload → 422; a second request with the same in-flight key → 409; a required key that's missing → 400.
• Concurrent read-modify-write: optimistic locking with a version column (UPDATE ... SET ..., version = version + 1 WHERE id = $1 AND version = $2; zero rows affected → 409/412) or JPA @Version (java-persistence); or SELECT ... FOR UPDATE inside one transaction when the operation must serialize.

Compatibility

Evolve additively; prefer a new optional field over renaming one in place; readers should ignore fields they don't recognise rather than failing closed (api-contract-openapi has the breaking-change procedure).

Formats

RFC 3339 timestamps in UTC; money as a decimal string or integer minor units, never a float; ids as strings even when they're numeric internally, so a client never silently loses precision.

Worked Example

❌ POST /tasks twice with the same client-generated request → two rows, two 201s
✅ POST /tasks with Idempotency-Key: <uuid> twice → first 201, second replays the same 201 body

❌ GET /tasks?page=50 on a 2M-row table → OFFSET 500000, a sequential scan
✅ GET /tasks?after=<cursor>&limit=50 → keyset WHERE, index-only scan

Common Mistakes

• Two different error shapes in the same service.
• A list endpoint with a default page size but no enforced maximum.
• A create endpoint with no idempotency story on a client that can legitimately retry (mobile, flaky network).
• Offset pagination on a table that will outgrow a few thousand rows.
• Money stored/returned as a float.

Red Flags

• A 500 response body that is actually a validation failure.
• OFFSET climbing past five digits in a hot path.
• A version/@Version field present on the entity but never checked in the update query.