Какие принципы построения REST API существуют?

Что проверяют

Отличаете ли вы REST от «любого JSON по HTTP». Аналитику его задают, чтобы понять, опишете ли вы контракт так, что разработчики не будут спорить о смысле полей и кодов. Дальше просят спроектировать пару ручек вслух: «как оформите поиск с фильтрами» или «какой код вернёте, если ресурс уже создан».

Как отвечать

Начните с ограничений Филдинга коротко: клиент-серверная модель, отсутствие состояния сессии на сервере, кэшируемость, единообразный интерфейс, слоистость, опциональный code on demand.

• ресурсы, а не действия: /orders/42/items, существительные во множественном числе, глагол несёт метод, а не адрес. /getOrder это RPC под видом REST;
• методы: GET безопасный, PUT и DELETE идемпотентные, POST нет. PUT заменяет представление целиком, PATCH меняет часть (JSON Merge Patch по RFC 7396 или JSON Patch по RFC 6902);
• коды: 201 с заголовком Location, 202 на асинхронную обработку, 204 на удаление, 400 против 422 (синтаксис против бизнес-валидации), 409 на конфликт, 429 с Retry-After;
• ошибки в одном формате: RFC 9457 Problem Details с полями type, title, status, detail плюс свой машиночитаемый код. Формат один для всех ручек, иначе каждый клиент пишет свой парсер;
• stateless: авторизация в каждом запросе (Bearer-токен), а не серверная сессия. Именно это позволяет поставить второй инстанс за балансировщиком;
• кэш и конкурентность: Cache-Control, ETag и If-None-Match на чтение, If-Match на запись от потери обновлений;
• пагинация и версии: курсор для лент, offset для небольших справочников, /v1 в пути, и ломающее изменение это новая версия.

Закончите документацией: контракт живёт в OpenAPI 3.1, из него генерируются клиенты и моки.

Где спотыкаются

Путают идемпотентность с безопасностью. Повторный DELETE идемпотентен, но безопасным не является: он меняет состояние.

Отвечают 200 с телом {"error": ...} на всё подряд. Клиент не может разбирать ошибки по коду, ретраи и кэширование ломаются.

Заявляют HATEOAS обязательным уровнем, но не могут сказать, зачем он в их API. Честнее назвать модель зрелости Ричардсона и признать, что большинство систем живут без гипермедиа.