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.