i have read quite few articles , lot of apigee documents , best practices designing restful api's pragmatic point of view. 1 thing cannot quite feel though whether building facility consumers of api optionally include other resources in same document or bad.
my gut feeling following avoided:-
/accounts?include=transactions { accounts: [ { "id": "101", ... "transactions": [ ... ] },... isn't better have:-
/accounts { accounts: [ { "id": "101", ... "transactions": /link/to/transactions/for/acccount },... and then
/transactions { "transactions": [ { "id": ... i'm not bothered conforming purist principles of rest eg. hateos etc. main reasons take view because:-
- to optionally load
/transactions/accountsmeans introduces coupling between service components delivering api - regardless of architecture (monolith or microservices)
is fair argument / approach?
you may want sidecar embedding.
one thing cannot quite feel though whether building facility consumers of api optionally include other resources in same document or bad.
well, it's not either of those. may suitable, or not suitable, use case, in correct setting opposite can case.
that said, if thinking in terms of rest, can't hurt @ reference implementation (www) does. dominant hyper media-type on web html; you've got representation, , links ancillary representations, absolutely no analog "here representation of document links to, in case".
in other words, there established, wildly successful precedent "link , let caches sort out". fielding himself wrote
query results represented list of links summary information, not arrays of object representations (query not substitute identification of resources).
another compromise support 2 resources; paired down version links, , rich version embedded data. geteventstore has pattern, 3 different resources
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 you present links both representations, , let clients choose 1 suitable circumstances; or (if using hateoas), control link relations appear in representations.
(another possibility have 1 resource, separate media type each representation).
you may want consider "aggregate" resource -- responsible making modifications domain model -- distinct many "projection" resources support queries, no modifications. cqrs approach.
jim webber: "you should expect have many many more resources in integration domain business objects in business domain."
