Реализация шаблона команды в API RESTful

Я нахожусь в процессе разработки HTTP API, надеюсь, сделать его максимально RESTful.

Есть некоторые действия, функциональность которых распространяется на несколько ресурсов, и иногда их нужно отменить.

Я подумал, что это звучит как шаблон команды, но как я могу смоделировать его в ресурс?

Я представлю новый ресурс под названием XXAction, такой как DepositAction, который будет создаваться через что-то вроде этого

POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...

это фактически создаст новый DepositAction и активирует его метод Do / Execute. В этом случае возвращение статуса 201 Created HTTP означает, что действие было успешно выполнено.

Позже, если клиент хочет посмотреть детали действия, он может

GET /action/{action-id}

Я думаю, что обновление / PUT должно быть заблокировано, потому что здесь это не актуально.

И чтобы отменить действие, я подумал об использовании

DELETE /action/{action-id}

который на самом деле вызовет метод Undo соответствующего объекта и изменит его статус.

Допустим, я доволен только одним Do-Undo, мне не нужно повторять.

Этот подход в порядке?

Есть ли подводные камни, причины не использовать его?

Это понятно из POV клиентов?

Вы добавляете в слой абстракции, который сбивает с толку

Ваш API начинается очень чисто и просто. HTTP POST создает новый ресурс Deposit с заданными параметрами. Затем вы сходите с пути, представляя идею «действий», которые являются деталями реализации, а не основной частью API.

В качестве альтернативы рассмотрим этот HTTP-разговор ...

POST / card / {card-id} / account / {account-id} / Депозит

AmountToDeposit = 100, разные параметры ...

201 СОЗДАН

Местонахождение = / карты / 123 / счет / 456 / Депозиты / 789

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

УДАЛИТЬ / карта / 123 / счет / 456 / депозит / 789

204 НЕТ СОДЕРЖАНИЯ

Потребитель API знает, что он имеет дело с ресурсом Deposit, и может определить, какие операции над ним разрешены (обычно через OPTIONS в HTTP).

Хотя реализация операции удаления сегодня осуществляется с помощью «действий», нет никакой гарантии, что при переносе этой системы, скажем, с C # на Haskell и поддержке внешнего интерфейса, вторичная концепция «действия» будет продолжать увеличивать ценность. в то время как основная концепция депозита, безусловно, делает.

Изменить, чтобы покрыть альтернативу УДАЛИТЬ и Депозит

Чтобы избежать операции удаления, но, тем не менее, эффективно удалить депозит, вы должны сделать следующее (используя общую транзакцию для учета пополнения и снятия):

POST / card / {card-id} / account / {account-id} / Транзакция

Сумма = -100 , разные параметры ...

201 СОЗДАН

Местонахождение = / карты / 123 / счет / 456 / транзакция / 790

Создается новый ресурс транзакции, который имеет абсолютно противоположную сумму (-100). Это приводит к балансу счета до 0, отменяя исходную транзакцию.

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

POST / card / {card-id} / account / {account-id} / Transaction / 789 / Undo <- ПЛОХО!

чтобы получить тот же эффект. Однако это нарушает семантику URI как идентификатора, вводя глагол. Вам лучше придерживаться имен существительных в идентификаторах и ограничивать операции с помощью глаголов HTTP. Таким образом, вы можете легко создать постоянную ссылку из идентификатора и использовать ее для GET и так далее.

Основная причина существования REST - устойчивость к сетевым ошибкам. Для этого все операции должны быть идемпотентными .

Базовый подход кажется разумным, но то, как вы описываете DepositActionтворение, не кажется идемпотентным, что следует исправить. Имея клиента уникального идентификатора, который будет использоваться для обнаружения дублирующих запросов. Таким образом, создание изменится на

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Если другой PUT с тем же URL-адресом сделан с тем же содержимым, что и ранее, ответ все равно должен быть, 201 createdесли контент такой же, и ошибка, если контент другой. Это позволяет клиенту просто повторно передать запрос в случае сбоя, поскольку клиент не может определить, был ли потерян запрос или ответ.

Имеет больше смысла использовать PUT, потому что он просто записывает ресурс и является идемпотентом, но использование POST также не вызовет никаких проблем.

Чтобы посмотреть детали транзакции, клиент будет иметь GETтот же URL, т.е.

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

и отменить его, он может удалить его. Но если это на самом деле имеет какое-либо отношение к деньгам, как предлагает образец, я бы предложил вместо этого ставить PUTting с добавленными «отмененными» флагами, хотя и для подотчетности (что остается след от созданной и отмененной транзакции).

Теперь вам нужно выбрать метод создания уникального идентификатора. У вас есть несколько вариантов:

1. Выдать клиентский префикс ранее в обмен, который должен быть включен.
2. Добавьте специальный запрос POST, чтобы получить пустой уникальный идентификатор с сервера. Этот запрос не должен быть идемпотентным (и на самом деле не может), потому что неиспользуемые идентификаторы не вызывают никаких проблем.
3. Просто используйте UUID. Все используют их, и ни у кого, кажется, нет никаких проблем ни с MAC, ни со случайными.