REST API: общая модель ресурсов (оболочка) для возвратов - PullRequest
Новая
       21

REST API: общая модель ресурсов (оболочка) для возвратов

0 голосов
/ 06 июня 2019

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

Позвольте мне проиллюстрировать:

Учитывая два API: Питание & Спорт (ресурс), как со стандартными операциями CRUD, так и чьи подписи являются стандартными .

Пример:

  • GET: ... / resource / {id}
  • POST: ... / resource
  • PUT: ... / resource / {id}
  • УДАЛИТЬ: ... / resource / {id}

Для вызова PUT / POST требуется, чтобы полезная нагрузка содержала объектную модель, например FoodModel или SportModel

Вопрос в том, есть ли что-то неправильное в том, чтобы все вызовы (GET / POST / PUT / DELETE) возвращали общую модель данных, у которой есть вложенный объект, который имеет сериализованный ресурс, где это необходимо.

Пример требуемой модели для отправки от абонента для POST ... / спорт 

{
  name: "soccer",
  popularity : "high"
}

Пример return модель для GET ... / sport / {1}

(! GET return, а не ответ от POST (думал, что это тоже может быть TransactionModel) 

{ "TransactionModel":{
                      correlationId: "83abaf27-3e87-43e5-a4ae-29eda793aff5",
                      anotherProperty1 : "...",
                      anotherProperty2 : "...",
                      resourceType : "Sport"
                      resourceValue : {
                                  name : "Soccer",
                                  popularity: "high",
                                  createdDate: "2019-06-05 23:06:32.923"
                                 }

}

Для пояснения, для вызова этих конечных точек требуются соответствующие модели в полезной нагрузке (для POST и PUT), поэтому SportModel / FoodModel

Мой объект ответа - TransactionModel с требуемой моделью ресурсов, содержащейся в нем. Это произойдет для всех ресурсов (спорт, еда, правила, человек и т. Д.)

Если у вас есть какие-либо статьи, документы RFC или что-то, что можно аргументировать за или против такого подхода. Пожалуйста, также предоставьте.

Спасибо

Ответы [ 2 ]

1 голос
/ 06 июня 2019

Вопрос в том, есть ли что-то неправильное в том, чтобы все вызовы (GET / POST / PUT / DELETE) возвращали общую модель данных, у которой есть вложенный объект, который имеет сериализованный ресурс, где это необходимо.

Краткий ответ: Нет.

Несколько более длинный ответ: нет, не в идеальных условиях. Но и в этом случае нет ничего невозможного.

Всемирная паутина - эталонное приложение для архитектурного стиля REST. HTML-документы обычно доставляются как представления ресурсов, и, вероятно, вы заметили, что в HTML-документе может быть значительное количество ... церемоний? ..., которые не имеют прямого отношения к состоянию ресурса.

И давайте посмотрим правде в глаза - независимо от того, каково ваше представление, само это представление внедряется в HTTP-сообщение, несущее свои собственные метаданные.

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

Архитектурно, ресурсы не ограничены одним и только одним представлением. Таким образом, вы можете выбрать поддержку application/json и application/prs.my-custom-app+json, предоставляя более богатую реализацию тем клиентам, которые достаточно воспитаны, чтобы попросить об этом.

Предполагаете ли вы, что если заголовок "Accept" был указан только для "application / json", ответом будет ожидаемая модель ресурса, например, SportModel. Где, как «application / pry.my-custom-app + json» возвращает модель «TransactionResult»?

Да, точно так же, как клиент, запрашивающий text/plain, может получить другое представление ресурса, чем клиент, запрашивающий text/html.

Вот комментарий 2008 от Роя Филдинга , который может дать вам более четкое представление о том, откуда это исходит

API REST должен потратить почти все свои описательные усилия на определение типов носителей, используемых для представления ресурсов и управления состоянием приложения, или на определение расширенных имен отношений и / или разметки с поддержкой гипертекста для существующих стандартных носителей. типы. Любое усилие, затрачиваемое на описание того, какие методы использовать с какими интересующими URI, должно быть полностью определено в рамках правил обработки для типа носителя (и, в большинстве случаев, уже определено существующими типами носителя). [Ошибка здесь подразумевает, что внешняя информация является движущей силой взаимодействия, а не гипертекста.]

0 голосов
/ 06 июня 2019

Нет! ты не делаешь ничего плохого.

Но я предпочитаю иметь разные объекты представления для каждого запроса и ответа, потому что на начальном этапе проекта это выглядит круто, но со временем появляются различные требования для ответа / запроса GET или, скажем, ответа / запроса POST, что испортит ваш код поскольку вы будете пытаться справиться с этими вещами с помощью этой общей модели данных или, скажем, объекта представления.

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

...