Какие сервисы можно назвать RESTful
Что проверяют
Знаете ли вы, что REST это набор архитектурных ограничений, а не «JSON поверх HTTP». Следом обычно спрашивают, что такое HATEOAS, почему большинство реальных API до него не доходит и как принципы выглядят в коде на Spring.
Как отвечать
REST описал Рой Филдинг в диссертации 2000 года. RESTful называют сервис, который соблюдает его ограничения:
- клиент-сервер: интерфейс и хранение данных развиваются независимо;
- отсутствие состояния (stateless): каждый запрос несёт всё нужное для обработки, включая токен. Сервер не хранит сессию клиента между запросами, при этом состояние ресурсов в базе, конечно, есть;
- кешируемость: ответ явно помечен как кешируемый или нет через
Cache-ControlиETag; - единый интерфейс: ресурсы адресуются URI, меняются через представления, сообщения самоописательны, а ответ содержит ссылки на допустимые переходы (HATEOAS);
- многоуровневость: клиент не знает, общается он с сервером напрямую или через балансировщик и кеш;
- код по запросу: единственное необязательное ограничение.
Для оценки удобна модель зрелости Ричардсона: на уровне 0 всё идёт через один эндпоинт, на первом появляются ресурсы, на втором правильные методы и коды ответа, на третьем гипермедиа. Большинство API, которые называют RESTful, живут на втором.
В Java это @RestController с @GetMapping, @PostMapping, @PutMapping, @DeleteMapping в Spring Web или @Path и @GET в Jakarta REST. Детали, которые стоит назвать: создание через POST возвращает 201 Created с заголовком Location (ResponseEntity.created(uri)), PUT заменяет ресурс целиком и идемпотентен, частичное изменение делается PATCH. Третий уровень даёт Spring HATEOAS с EntityModel и linkTo(methodOn(...)).
Где спотыкаются
Называют REST протоколом или сводят единый интерфейс к формату JSON. Формат представления может быть любым, стиль его не диктует.
Проектируют URI глаголами: /getUser, /deleteOrder, POST /updateStatus. Действие выражается методом, а URI обозначает ресурс.
Отвечают 200 OK с {"error": ...} в теле. Клиенты, прокси и мониторинг ориентируются на код ответа, и такая ошибка для них выглядит успехом.