REST API: статусы, согласование и семантика

Ресурсы и HTTP-глаголы

REST моделирует домен как ресурсы (существительные в URL: /orders/42), а действия выражает HTTP-методами: GET (прочитать), POST (создать), PUT (заменить целиком), PATCH (частично обновить), DELETE (удалить).

Глаголы в URL (/getOrder, /createOrder) — антипаттерн: глагол несёт сам HTTP-метод, а путь именует ресурс.

Статус-коды как часть контракта

Код ответа — это контракт, а не украшение. 2xx: 200 OK, 201 Created (новый ресурс, обычно + заголовок Location), 204 No Content (успех без тела). 4xx — вина клиента: 400 (некорректный запрос), 401 (не аутентифицирован), 403 (нет прав), 404 (нет ресурса), 409 (конфликт), 422 (валидация). 5xx — вина сервера.

Частые ошибки: возвращать 200 с телом-ошибкой, или 500 на невалидный ввод (это 400/422). Явный статус задают через ResponseEntity или @ResponseStatus.

@PostMapping
ResponseEntity<Order> create(@RequestBody NewOrder req) {
    Order o = service.create(req);
    return ResponseEntity.created(URI.create("/orders/" + o.id())).body(o); // 201 + Location
}

Content negotiation и конвертеры

Клиент сообщает желаемый формат заголовком Accept, а формат тела — Content-Type. Spring подбирает HttpMessageConverter под эти заголовки; для JSON это Jackson, который сериализует/десериализует объекты автоматически.

produces/consumes на маппинге сужают, какие типы метод отдаёт/принимает. Поведение Jackson настраивают аннотациями (@JsonProperty, @JsonIgnore) и глобально (ObjectMapper bean).

Идемпотентность и семантика методов

Идемпотентность — повтор запроса даёт тот же эффект. GET, PUT, DELETE идемпотентны (повторный PUT с теми же данными не меняет результата), а POST — нет (два POST создадут два ресурса). Это важно для ретраев: безопасно повторять идемпотентные методы.

PUT заменяет ресурс целиком, PATCH меняет частично. Для небезопасного POST при ненадёжной сети применяют ключ идемпотентности (Idempotency-Key), чтобы повтор не создал дубль.

Версионирование и HATEOAS

API эволюционирует, поэтому его версионируют: через путь (/api/v1/...), заголовок или media type. Путь — самый простой и распространённый вариант.

HATEOAS (гиперссылки на связанные действия в ответе) — высшая ступень REST по Ричардсону; на практике применяется редко, но знать концепцию полезно: ответ несёт не только данные, но и доступные переходы.

Как отвечать на собеседовании

Свяжите ресурсы + HTTP-глаголы и подчеркните статус-коды как контракт (201+Location, 400/422 на валидацию, 409 на конфликт — не 200/500 на всё). Объясните content negotiation через Accept/Content-Type и Jackson-конвертеры, идемпотентность GET/PUT/DELETE vs POST (важно для ретраев) и способы версионирования.