---
title: "REST contracts, validation, and errors"
chapter: "07"
---

# REST contracts, validation, and errors

An API contract includes more than a URL. It defines methods, schemas, status
codes, errors, authentication, idempotency, pagination, and compatibility.

## Resource design

Use nouns for resources and HTTP semantics intentionally. `GET` reads, `POST`
creates or commands, `PUT` replaces, `PATCH` changes part, and `DELETE` removes.
Return `201 Created` with a location for creation when appropriate.

## Validation

Validate syntax and shape at the controller boundary. Validate business rules
inside the application/domain layer. A syntactically valid order can still
violate credit or inventory rules.

## Errors

Use `@ControllerAdvice` and exception handlers to produce a consistent,
machine-readable error format. Problem Details is a useful HTTP standard.
Do not leak stack traces, SQL, internal hostnames, or secrets.

## Compatibility

Prefer additive changes. Make consumers tolerant of new fields. Deprecate with
measurements and a removal date. Use contract tests for important consumers.

## Idempotency

For retryable commands such as payment or order creation, accept an idempotency
key and store the completed outcome. Retries should not duplicate business
effects.

## Feynman check

An API is a restaurant menu and ordering rule. Validation checks whether the
order is readable. Business rules check whether the meal can actually be sold.
A stable error format is the clear explanation when it cannot.