Rest uri design для изменения статуса ресурса

Question

У меня есть ресурс, который может быть доступен в URI /resources/{resource_identifier}, и он имеет свойство «status», которое я хочу быть доступным. Я подумал о нескольких вариантах этого, что было бы «лучшим» или «самым RESTfull»?

Вариант Один Append действия на URI и есть клиент POST этих URIs

/resources/{resource_identifier}/void  
/resources/{resource_identifier}/open  
/resources/{resource_identifier}/close 

Это выглядит неуклюжим, хотя.

---

Вариант второй Используйте PARAM запрос в URI и клиент PATCH к этим

/resources/{resource_identifier}?transition=void 
/resources/{resource_identifier}?transition=open 
/resources/{resource_identifier}?transition=close 

---

Вариант Три использования полезной нагрузки запроса и есть клиент PUT

/resources/{resource_identifier} 

варианты полезной нагрузки:

{ ..., "status" :"void" } 
{ ..., "status" :"open" } 
{ ..., "status" :"close" } 

---

Или, может быть что-то совсем другое?

Answer 1

Ваш второй вариант выглядит лучше, потому что вы поддерживаете структуру URL-адреса RESTful и не добавляете методы стиля RPC в конец.

Почему бы просто не сделать это:

PUT к /resources/:id и отправлять данные transition=void с запросом.

Он ведет себя так же, как если бы вы получали запрос POST, просто извлеките данные из тела запроса.

Answer 2

Почему бы не иметь «статус» в качестве ресурса. Вы можете управлять им. Также предположите, что уже существует статус «статус», созданный как часть создания ресурса {resource_identifier}, и для статуса уже есть значение по умолчанию.

Тогда бизнес-логика должна просто «обновить» статус с помощью остального вызова и, следовательно, «PUT» следует использовать.

обновленный Перемещение состояния в Пут-Body

PUT: /resources/{resource_identifier}/status/ 

Body: {void | open | close } 

Answer 3

Первый вариант явно не ОТДОХНУТЬ; вы имеете «действия» в URI и используете POST, что должно создать новый ресурс, который вы явно не пытаетесь сделать.

Рассматривая только формат URI на данный момент. Второй вариант улучшается, но строки запроса такого характера больше для , читающих данных. Ничто действительно не мешает вам делать это таким образом. Вариант 3 имеет наилучший формат URI, он ссылается только на то, какой ресурс вы хотите ссылаться в своем запросе.

Если мы сейчас рассмотрим метод запроса. В моей книге это довольно просто, я полагаю, что статус - это только одно поле этого ресурса, поэтому, если вы делаете только частичное обновление, вы исправляете ресурс, и поэтому PATCH - это метод использования. В случае случайности «статус» является единственным свойством, тогда изменение состояния полностью меняет ресурс, и поэтому PUT будет приемлемым; но я сомневаюсь, что это действительно так.

В его нынешнем виде URI третьего варианта, в сочетании с использованием PATCH, вероятно, является лучшим вариантом.

PATCH /resources/{resource_identifier} 

{ "status" :"close" } 

Конечно, вы можете также совместить это с концепцией раскрывающих конкретные атрибуты с помощью своего собственного URI, как если бы они были ресурс в своем собственном праве. Честно говоря, мне это не нравится, поскольку оно кажется довольно странным и работает только по одному атрибуту за раз. Тем не менее, если это то, что вы хотите использовать, вы могли бы иметь что-то вроде:

PUT /resources/{resource_identifier}/status 

close 

---

Имейте в виду, что нет «правильный» способ сделать REST, просто «не плохо» пути. Это стиль, а не набор правил.

Я также предлагаю вам подумать, что возможность брать много форматов является желательной особенностью, вообще говоря. Таким образом, первый вариант, как правило, легче работать. Вы можете взять JSON в качестве примера или обменять его на XML <status>close</ status> или на пару простых значений ключа status=closed и т. Д.