Блог

В моем api есть ресурс задания, который содержит атрибут состояния. Состояние задания может быть «запланировано», «обработка» или «выполнено». Состояние заданий определяется на стороне сервера. Когда состояние заданий «обрабатывается», а процесс ETL запускается на стороне сервера.

Я хочу, чтобы клиент мог запускать действие типа «пуск», которое устанавливало бы состояние заданий на «обработка» или запускало действие «стоп», которое сбрасывало бы состояние заданий на «запланированное».

Мой вопрос здесь в том, как я должен обрабатывать эти «пользовательские» действия в REST?

Я вижу два возможных подхода:

• Я мог бы создать две новые конечные POST /job/:id/start
POST /job/:id/stop точки.

• Я мог бы создать одну конечную точку, которая принимает запрос-параметр действия. POST /job/:id?action=start
POST /job/:id?action=stop

Я не уверен, что считается более RESTful, если либо?

Кроме того, я не уверен, каким должен быть код ответа? Я предполагаю одно из следующих: 200 (OK) , 202 (Accepted) , 204 (No content) но не уверен, что будет лучше. Например, если api вернул ответ 200, должен ли тело ответа содержать ресурс задания с обновленным состоянием? Или API должен просто возвращать 204 без содержимого?

REST не заботится о бизнес-логике, только о ресурсах — поэтому наиболее рациональным подходом было бы ПОМЕСТИТЬ туда /job/:id , где отправленный документ будет содержать новый статус.

Хотя технически «правильное» решение (не говорите Рою Филдингу) Я скорее предпочитаю явные «действия», например /job/:id/start , потому что это позволяет моему ресурсу возвращать ссылки на эти действия, чтобы сообщить клиенту, возможно ли соответствующее действие или нет (например, ПЕРЕХОД к «остановленному» заданию будет содержать ссылку для запуска этого задания).

На основе кодов состояния HTTP я обычно возвращаю 204, когда меня не интересует результат, хотя в вашем случае 200 с обновленным ресурсом было бы правильным — только когда вы, например, «запускаете» уже запущенное задание, 304 Не измененное будет правильным с точки зренияклиент как состояние не изменилось бы.

Я бы выбрал 202 Принято, если запуск задания не оказывает прямого влияния на ресурс, потому что задание будет, например, помещено в очередь и обновлено только позже, чтобы клиент знал, что было запущено асинхронное действие.