REST API – памятка
Несколько рекомендаций к REST API.
Общие рекомендации
- Создавайте API всегда и только под конкретные сценарии потребления.
- Разумно оптимизируйте количество методов, делая их более универсальными.
- Входные параметры делайте массивами, если это может упростить сценарий использования API.
- Указывайте параметры в:
• header – для передачи технического, системного, глобального контекста
• path – для передачи идентификатора объекта
• query – для передачи управляющих опций, параметров
• requestBody – для передачи данных - Используйте выделенные методы, если нужно выполнить изменение атрибута объекта по особому алгоритму.
- Не используете множественное наследование в объектах.
- Используйте опции readOnly и writeOnly, чтобы оптимизировать количество объектов в контракте.
Доступ к подчиненной сущности через предметную сущность
DELETE /team/{team-id}/member/{member-id}:
Реализуйте доступ к подчиненным сущностям через предметную сущность (корень агрегата – team-id), но не доверяйте ему. Может показаться, что team-id лишний, ведь для удаления достаточно member-id, но team-id позволит ускорить выполнение операции, так как можно выполнить параллельно:
• проверку Row Level Security на уровне предметной сущности;
• проверку, что member-id подчинена именно team-id;
• часть основной операции.
POST – PUT – PATCH
POST и PUT используйте, если вы передаете полное описание объекта. Если вы хотите выполнить обновление объекта слиянием, т.е. передать произвольную часть объекта, то рекомендую использовать PATCH.
POST – применяется, если пользователь (фронт) считает, что он передает новый объект. Объект передается целиком. В БД это реализуется операцией INSERT.
PUT – применяется, если пользователь (фронт) считает, что он обновляет объект. Объект передается целиком. В БД это может реализовываться операцией UPDATE или UPSERT или UPDATE + INSERT версионной строки.
PATCH – для замены части объекта (фронт отдает произвольный набор свойств).
Процессные атрибуты
У объекта могут быть процессные атрибуты, например: состояние, исполнитель. Рекомендуется выделить их в отдельную процессную сущность. Для изменения же самих атрибутов можно использовать обособленные методы.
POST /orders/{order-id}/set-state
POST /orders/{order-id}/set-manager
Не используйте нотацию CamelCase
Разработчики таблиц в БД часто любят давать полям имена с цифрами, например: agg12_3, agg1_23, agg1_2_3 (особенно в промышленном ИТ). При попытке привести имя к нотации Camel вы получите проблему: конфликт имен, непонятное имя, длинное имя. Camel плохо подходит для работы с цифровыми именами, используйте Kebab. Между удобством чтения и компактностью стоит выбрать первое.
» Для справки, имена переменных в HTTP-заголовках в нотации Train (Kebab + Camel).