One of the most important design principles for an API program is to embrace that APIs are products. It follows that successful APIs, much like products, must provide user-optimized experiences. Case in point: it is clearly inappropriate to send a mobile application large response payloads. Your API may get away with it when responding to a request from an enterprise system communicating over a high-speed fiber-optic connection. Some clients may even want to get a rich response, but in general assuming that network is reliable and/or bandwidth is infinite is a fallacy, on the web.
especially read the comment section
http://spec.transclude.io
spec.transclude.io
Transclude Preference for the HTTP Prefer Header
The specification for Transclude preference is an extension to the Prefer Header for HTTP
is referred there
Transclude preference notifies the server that the client would prefer the server to proactively transclude certain content represented by links of indicated link relation types. The notion of "link relation type", in this context is as defined by [RFC5988].
I really like that concept .. and it provides some means of the client controlling the scope of the resource representation .. which i think your main question was
From a convo on mantis-api channel:
I am curious what others think .. so yes, chattiness is a concern .. and this is one of the primary drivers behind graphQL http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html Creating Client-Optimized Resource Representations in APIs
One of the most important design principles for an API program is to embrace that APIs are products. It follows that successful APIs, much like products, must provide user-optimized experiences. Case in point: it is clearly inappropriate to send a mobile application large response payloads. Your API may get away with it when responding to a request from an enterprise system communicating over a high-speed fiber-optic connection. Some clients may even want to get a rich response, but in general assuming that network is reliable and/or bandwidth is infinite is a fallacy, on the web.
especially read the comment section http://spec.transclude.io spec.transclude.io Transclude Preference for the HTTP Prefer Header The specification for Transclude preference is an extension to the Prefer Header for HTTP is referred there