Проектирование REST API: спорные вопросы с проектов и собеседований

Конспект статьи. Автор оригинала: Екатерина Ананьева (katherine_a, GetAnalyst)

REST — стиль без жёстких правил (описан Роем Филдингом в 2000 году), поэтому многие решения субъективны. Семь спорных вопросов с рекомендациями.

1. POST для получения данных — да, если фильтров много и URL становится нечитаемым, а также для асинхронных задач: POST создаёт задачу и возвращает её ID, GET по ID отдаёт статус и результат.
2. Все методы через POST — технически можно, но нарушается семантика и пропадает кеширование.
3. Тело в GET — спецификация не запрещает, но многие клиенты и серверы его игнорируют. Не стоит.
4. Единственное или множественное число — оба варианта допустимы, гайдлайны Microsoft и Google чаще за множественное. Главное — единообразие.
5. Глаголы в URL — не нужны: вместо POST /products/create — POST /products.
6. 200 или 201 на POST — при создании ресурса 201 Created.
7. Пустой результат — для списка 200 и пустой массив, для конкретного объекта 404.

Решения фиксируют в гайдлайне команды, а при развитии существующего API следуют уже принятой логике.