Какие принципы построения REST API существуют?
Что проверяют
Отличаете ли вы архитектурные ограничения REST, сформулированные Роем Филдингом, от набора привычных договорённостей про URL и коды ответа. Следом обычно просят спроектировать пару эндпоинтов и спрашивают, чем PUT отличается от PATCH и какой код вернуть при создании ресурса.
Как отвечать
Сначала шесть ограничений из диссертации Филдинга:
- клиент-сервер: интерфейс и хранение данных развиваются независимо;
- stateless: каждый запрос несёт всё нужное для обработки, сессии клиента на сервере нет. База данных при этом есть, речь только о состоянии диалога;
- кэшируемость: ответ сам говорит, можно ли его кэшировать, через
Cache-ControlиETag; - единообразный интерфейс: ресурсы адресуются URI, меняются через представления, сообщения самоописательны, а в строгом варианте ответ содержит ссылки на следующие действия (HATEOAS);
- многоуровневость: клиент не знает, говорит он с сервером или с прокси и балансировщиком;
- код по запросу: единственное необязательное ограничение.
Потом практика на ASP.NET Core. Ресурсы называются существительными во множественном числе: /api/orders/42. Методы по семантике: GET безопасен, PUT и DELETE идемпотентны, POST нет. На создание 201 Created с заголовком Location, в контроллере это CreatedAtAction, в Minimal API Results.Created. Ошибки в формате ProblemDetails (RFC 9457), а атрибут [ApiController] сам вернёт 400 при невалидной модели. Добавьте версионирование через пакет Asp.Versioning и описание в OpenAPI: в шаблонах .NET 9 для этого встроенный Microsoft.AspNetCore.OpenApi, а Swashbuckle больше не подключается по умолчанию.
Где спотыкаются
Перечисляют CRUD-методы и коды ответа и называют это принципами REST. Это соглашения, а ограничения Филдинга звучат иначе.
Возвращают 200 OK на всё, а ошибку кладут в тело. Клиенты, прокси и мониторинг перестают понимать, что запрос не удался.
Путают 401 и 403: первый про то, что вы не аутентифицированы, второй про то, что аутентифицированы, но прав нет.