Массовая манипуляция с помощью REST (RESTful) API

Question

Я хотел бы получить совет по разработке REST API, который позволит клиентам эффективно добавлять / удалять большое количество объектов в коллекцию.

Через API клиенты должны иметь возможность добавлять элементы в коллекцию и удалять элементы из нее, а также управлять существующими элементами. Во многих случаях клиент захочет сделать массовые обновления коллекции, например, добавление 1000 элементов и удаление 500 различных элементов. Такое ощущение, что клиент должен иметь возможность сделать это за одну транзакцию с сервером, а не требовать 1000 отдельных запросов POST и 500 DELETE.

Есть ли у кого-нибудь информация о лучших практиках или соглашениях для достижения этой цели?

В настоящее время я думаю, что нужно иметь возможность помещать объект, представляющий изменение в URI коллекции, но это, кажется, расходится с HTTP 1.1 RFC , что, по-видимому, предполагает, что данные, отправленные в запрос PUT должен интерпретироваться независимо от данных, уже присутствующих в URI. Это подразумевает, что клиент должен будет отправить полное описание нового состояния коллекции за один раз, которое может быть намного больше, чем изменение, или даже больше, чем клиент узнает, когда он сделает запрос.

Очевидно, я был бы рад отклониться от RFC в случае необходимости, но предпочел бы сделать это обычным способом, если такая конвенция существует.

Answer 1

Возможно, вы захотите рассматривать задачу изменения как ресурс сам по себе. Таким образом, вы действительно помещаете один объект, который является объектом массового обновления данных. Возможно, у него есть имя, владелец и большой двоичный объект CSV, XML и т. Д., Который необходимо проанализировать и выполнить. В случае CSV вы также можете определить тип объектов, представленных в данных CSV.

Список заданий, добавление задания, просмотр статуса задания, обновление задания (возможно, для его запуска / остановки), удаление задания (его остановка, если оно выполняется) и т. Д. Эти операции легко отображаются на REST API дизайн.

Как только вы это сделаете, вы можете легко добавить различные типы данных, с которыми может работать ваш пакет обновления данных, возможно, даже смешать их вместе в одной задаче. Другими словами, нет необходимости дублировать один и тот же API во всем приложении для каждого типа вещей, которые вы хотите импортировать.

Это также очень легко поддается реализации фоновых задач. В этом случае вы, вероятно, захотите добавить поля к отдельным объектам задачи, которые позволяют клиенту API указывать, как они хотят получать уведомления (URL-адрес, по которому они хотят вас получить, когда это будет сделано, или отправить им электронное письмо и т. Д.) .

Answer 2

Да, PUT создает / перезаписывает, но не обновляет частично.

Если вам нужна семантика частичного обновления, используйте PATCH. Смотри http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-14.html.

Answer 3

Для POST, по крайней мере, кажется, что вы должны иметь возможность POST к URL-адресу списка и иметь тело запроса, содержащего список новых ресурсов вместо одного нового ресурса.

Answer 4

Вы должны использовать AtomPub . Он специально разработан для управления коллекциями через HTTP. Может даже быть реализация для вашего языка.

Answer 5

Насколько я понимаю, REST означает REpresentational State Transfer, поэтому вы должны передавать состояние от клиента к серверу.

Если это означает, что слишком много данных идет назад и вперед, возможно, вам нужно изменить свое представление. Структура collectionChange будет работать с серией удалений (по идентификатору) и дополнений (со встроенными полными представлениями xml), POSTed для URL-адреса интерфейса обработки. Реализация интерфейса может выбрать собственный метод для удаления и добавления на стороне сервера.

Самая чистая версия, вероятно, будет определять элементы по URL, а коллекция содержит серию URL. Новая коллекция может быть PUT после изменений клиентом, после чего следует ряд PUT добавляемых элементов и, возможно, серия удалений, если вы хотите фактически удалить элементы с сервера, а не просто удалить их из этого списка.

Answer 6

Вы можете ввести мета-представление существующих элементов коллекции, для которых не требуется передавать все их состояние, поэтому в каком-то абстрактном коде ваше обновление может выглядеть так:

{existing elements 1-100}
{new element foo with values "bar", "baz"}
{existing element 105}
{new element foobar with values "bar", "foo"}
{existing elements 110-200}

Добавление (и изменение) элементов выполняется путем определения их значений, удаление элементов - без упоминания о том, что новый набор и переупорядочение элементов выполняется путем указания нового порядка (если порядок сохраняется вообще).

Таким образом, вы можете легко представить всю новую коллекцию без необходимости повторной передачи всего контента. Использование заголовка If-Unmodified-Since гарантирует, что ваше представление о контенте действительно соответствует идее серверов (чтобы вы случайно не удалили элементы, о которых вы просто не знали, когда был отправлен запрос).