[berkes]

> why not just include that JSON in the original document, instead of linking to it?

For me, the reason I'm linking and not including is bandwidth (and load of (de-)serialization). The age-old "pointer vs value" optimization.

When you go overboard, the "state" part of the payload becomes a large part of whats being sent. I've worked with APIs where over 80% of the data was this "cruft" and only 20% was the actual data. It happens esp when you compose your API of many small objects - which in itself has tradeoffs but is often a good practice.