В конце прошлой недели я дала постановку задачи на интеграционный REST API метод:
при удалении задачи в системе #EventTasksGA нужно автоматически удалять её и в системе Todoist.
Но я не обосновала, почему делаю метод:
DELETE /event/{eventId}/task/{taskId} - удаление задачи из мероприятия
Это метод на стороне нашей системы EventTasksGA. Его описывают системные аналитики и/или Backend-разработчики.
Обоснование:
1. DELETE
Этот HTTP-метод выбран, потому что отвечает за удаление.
Ошибки:
❌ Делать
POST /task/{taskId}/delete
или
POST /delete-task/{id}
и т.п.
Не надо тащить глагол действия delete в URL.
Действие удаления выбирается на уровне HTTP-метода.
Аналогично будет с другими действиями.
2. https://test.com/api/v1/event/{eventId}/task/{taskId}
Такой URL выбран, потому что задачи task всегда создаются внутри мероприятий event.
Альтернативные варианты:
👌 /task/{taskId} - т.к. у каждой задачи в системе в любом случае будет свой уникальный id, то не обязательно создавать дополнительную вложенность (мероприятие -> задача)
👌 /task?taskId={id} - можно делать id задачи как query-параметр (после ?), но более распространенная практика использовать path-параметр, как в решении.
Ошибки:
❌ Глагол действия в URL.
❌ Отсутствие id задачи в URL под предлогом, что оно должно быть в body (json).
3. Тело запроса Body (JSON)
Отсутствует.
Вся необходимая информация уже передается в URL.
Также в DELETE обычно не определяют тело запроса (подтверждающий источник).
Чтобы самостоятельно разобраться с проектированием REST API с нуля, рекомендую последовательно познакомиться с материалами:
📚 Протокол HTTP и его связь с REST API
📚 Картинка к посту
📚 Структура постановки задачи на REST API метод
📚 Связь БД и дизайна REST API
📚 Проектирование REST API: спорные вопросы с проектов и собеседований
📚 Вопросы и ответы по REST API: собеседование на системного аналитика
#RestApiGA #ИнтеграцииGA