api-design-conventions

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
}