Патч против слияния-патч, который подходит? - PullRequest
0 голосов
/ 07 мая 2019

пытается выяснить, какие модели лучше всего подходят для api (низкие обновления, но структура объектов может часто меняться, приложение с высоким уровнем чтения)

У меня есть такой ресурс

  1. Эпический (идентификатор, имя, описание, дата начала, дата закрытия, статус, истории )
  2. История (идентификатор, имя, описание, дата начала, дата закрытия, статус, задачи )
  3. задача (идентификатор, имя, описание, дата начала, дата разрешения, разрешение)

Если мне требуется поддержка только их обновления,

  1. update Epic имя или описание или даты или статус
  2. update Story имя или описание или даты или статус
  3. обновление Задание имя или описание или даты или статус

что имеет смысл?

PATCH с application/merge-patch+json RFC 7396

ресурс должен соответствовать структуре целевого объекта

  1. epics / {id}
  2. epics /{ID1} / рассказы /{id2} .. и так далее

PATCH с application/json - Я склонен выбрать это , так как в этом нет необходимостиприменять RFC 7396 и гибкость для обновления правил обновлений.

ваши настраиваемые правила для обновления (но технически - я мог бы просто отправить атрибуты ресурса, для которых нужны обновления, аналогичные application/merge-patch+json)

  1. эпопей / {id}
  2. эпопей / {id1} / story / {id2} .. и т. Д.

PUT с application/json

ресурс должен соответствовать всем полям и создавать новый объект и заменять (или обманывать и просто обновлять только как в патче)

  1. epics / {id}
  2. epics / {id1} / Stories / {id2} .. и т. д.

PUT с application/json

или чит и просто обновитьтолько как в патче, но используйте put

  1. epics / {id}
  2. epics / {id1} / Stories / {id2} .. и т. д.

1 Ответ

2 голосов
/ 08 мая 2019

С точки зрения REST, важно помнить о едином интерфейсе - у вас есть некоторый ресурс с представлением application/json.Я могу GET ваше представление и вносить в него локальные изменения, используя любой мой любимый инструмент.

Если я затем хочу предложить изменить ресурс, чтобы он соответствовал моему представлению, мы выбираем подходящий метод из протокола HTTP.Другими словами, все методы HTTP являются частью домена «транспортировать этот документ по сети».(Ссылка: Джим Уэббер, 2011 ).

Таким образом, поддержка «всех из них» - это реальный способ обеспечить максимально возможное количество универсальных клиентов для взаимодействия с вашими ресурсами.

PUT /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json

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

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

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: ????

Это совершенно разумный способ борьбы с небольшимименяется на большие представления.Вы отказываетесь от некоторых преимуществ PUT - с потерянными сообщениями теперь сложнее иметь дело.

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json

Ни в коем случае.application/json не является форматом документа патча - у вас нет возможности узнать, какие изменения описываются таким представлением, без каких-либо внеплановых разногласий.

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/vnd.example.patch+json

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/prs.example.patch+json

Это «ОТДЫХ» способ сделать предыдущий бит;вы определяете пользовательский тип мультимедиа и документируете семантику, и тогда любой клиент, который реализует ваш тип мультимедиа, может использовать его.Доступны дерево продавцов и дерево тщеславия .Бит +json - это суффикс структурного синтаксиса , который предлагает подсказку структуры для потребителей, которые не распознают базовый подтип.

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json-patch+json

PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/merge-patch+json

Также отличный выбор, поскольку эти дватипы были стандартизированы в RFC 6902 и RFC 7936 ;у вас гораздо больше шансов, что клиент уже будет знать эти типы.

Клиент, который знает о HTTP PATCH , вероятно, также будет знать, как использовать метод OPTIONS, чтобы узнать, какие методы и патч форматов документов сервер готов к обработке.

OPTIONS /31E772D3-0157-4B52-8243-75EEAB946E65

HTTP/1.1 204 No Content
Allow: OPTIONS, GET, HEAD, PUT, PATCH
Accept-Patch: application/prs.example.patch+json, application/json-patch+json, application/merge-patch+json
...