Как лучше спроектировать REST API?

Question

[Rodion]

Приветствую!

При проектировании API столкнулся с непониманием идемпотентности методов в контексте бизнес-логики. Прошу помощи.

Предположим, есть сервис включения, выключения и перезагрузки компьютеров и каждая операция здесь - асинхронна (чтобы клиент не ждал ответа); тогда логично иметь вот такие ресурсы и методы к ним:

• POST /api/computers/runs/operations - запуск компьютера (в ответ - асинхронная операция с идентификатором)
  
• GET /api/computers/runs/operations/{operation:uuid} - получение информации по операции запуска
  
• GET /api/computers/runs/operations - листинг всех операций
  
• POST /api/computers/shutdowns/operations - выключение компьютера (в ответ - асинхронная операция с идентификатором)
  
• ... примерно такой же набор методов как и выше, но только для перезагрузки
  

Теперь по бизнес-логике встаёт вопрос об отмене операции запуска и тут на ум приходит два варианта (собственно у меня сложность в выборе одного из двух, чтобы это было наиболее логично):

• DELETE /api/computers/runs/operations/{operation:uuid}
  
• POST /api/computers/runs/operations/{operation:uuid}/cancels
  

Важно учесть, что сам объект операции я удалять из базы не хочу: я всего лишь хочу изменить его состояние на operation.canceled=True, например; и первый метод в таком случае выходит более простым и логичным. И я так же уверен, что детали реализации (удаление записи или смена состояния этой записи) не должны быть основополагающими при проектировании ресурсов и методов к ним.

Что скажете?

Answer 1

[Василий Банников]

Какие-то больно странные пути.
А вообще да - тут всё POST-ами должно быть, тк нельзя отменить отменённую операцию.
Ну и имхо, такая логика плохо на rest кладётся, так что вполне ок сделать

На создание новой задачи
POST /api/machines/{machineId}/jobs
И в теле указать, что это start/stop/reset

На отмену
POST /api/machines/{machineId}/jsobs/{jobId}/cancel
Не DELETE, тк по семантике, после DELETE ресурс должен исчезнуть.

На получение списка
GET /api/machines/{machineId}/jobs

На получение инфы по конкретной задаче
GET /api/machines/{machineId}/jobs/{jobId}

Если нужно получить список задач на включение:
GET /api/machines/{machineId}/jobs?type=start

По именованию, кмк, лучше выглядит слово "machine" и "job", а не "computer" и "operation"