REST as nouns, verbs, and status codes

HTTP is a domain language — use it fluently

A well-designed REST API communicates its intent in the URL, method, and status code. The body is for data, not for error reporting. Clients should be able to tell what happened from the HTTP response line alone, then use the body for detail.

• GET /invoices/42: 200 with body, or 404 if missing.
• POST /invoices: 201 with Location: /invoices/43 header.
• PATCH /invoices/42: 200 with updated resource.
• DELETE /invoices/42: 204 No Content on success.
• 409 Conflict when the domain refuses a transition.
• 422 Unprocessable when the payload is syntactically valid but semantically wrong.

@PostMapping
ResponseEntity<InvoiceDto> create(@Valid @RequestBody CreateInvoiceRequest req) {
    Invoice saved = service.create(req.toCommand());
    return ResponseEntity
        .created(URI.create("/api/invoices/" + saved.id()))
        .body(InvoiceDto.from(saved));
}

Error responses should be uniform

Pick a single error shape — RFC 7807 Problem Details for HTTP APIs is a strong default — and make every failure (validation, not-found, conflict, server error) use it. Clients can parse one schema instead of five ad-hoc ones.