Правила композитных ответов?

Question

Я прочитал немало статей и много документов Apigee и рекомендации по разработке API RESTful с прагматической точки зрения. Одна вещь, о которой я не могу понять, - это то, является ли создание объекта для потребителей API необязательным включением других ресурсов в один и тот же документ, является хорошим или плохим.

Мое шестое чувство, что следующее будет вообще избегать: -

/accounts?include=transactions 

{ accounts: [ 
    { "id": "101", 
     ... 
     "transactions": [ ... ] 
    },... 

Не лучше иметь: -

/accounts 

{ accounts: [ 
    { "id": "101", 
     ... 
     "transactions": /link/to/transactions/for/acccount 
    },... 

, а затем

/transactions 

{ "transactions": [ 
    { "id": ... 

Я не беспокоюсь о том, чтобы соответствовать пуристским принципам REST, например. HATEOS и т.д. Основные причины я принимаю эту точку зрения, потому что: -

1. Чтобы дополнительно нагрузку /transactions в мой /accounts означает, что это вводит связь между компонентами услуг, доставляющих API - это независимо от архитектуры (Монолит или Microservices)

Является ли это справедливым аргументом/подходом?

Answer 1

Вы также можете ознакомиться с sidecar embedding.

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

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

Сказанное, если вы думаете с точки зрения ОТДЫХА, это не может повредить, чтобы посмотреть, что делает эталонная реализация (WWW). Доминирующим гипер-медиа-текстом в Интернете является HTML; у вас есть представление и ссылки на вспомогательные представления, но абсолютно никакого аналога для «вот представление чего-то, на что этот документ ссылается, на всякий случай».

Другими словами, существует установленный, дико успешный прецедент для «ссылки на все и позволяющие кэшам разобраться». Fielding себя wrote

результатов запроса представлены в списке ссылок с краткой информацией, а не массивами объектных представлений (запрос не является замена для идентификации ресурсов).

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

http://127.0.0.1:2113/streams/newstream2 
vs 
http://127.0.0.1:2113/streams/newstream2?embed=rich 
vs 
http://127.0.0.1:2113/streams/newstream2?embed=body 

Вы можете представить ссылки на оба представления, и пусть ваши клиенты выбрать один наиболее подходящий для их обстоятельств; или (если вы используете HATEOAS), вы можете контролировать, какие отношения ссылок появляются в представлениях.

(Еще одна возможность - иметь один ресурс, но для каждого представления - отдельный тип материала).

Вы также можете подумать, что «совокупный» ресурс - ответственный за внесение изменений в модель вашего домена - может отличаться от многих «проекционных» ресурсов, которые поддерживают запросы, но никаких изменений. Это подход CQRS.

Джим Уэббер: «Вы должны ожидать, что у вас будет гораздо больше ресурсов в вашем домене интеграции, чем на бизнес-объекты в вашем бизнес-домене».