However in some recent discussions Jim mentioned that he would like to have response envelope on every entry point for different purpose. Since we will have envelope anyway we might as well use it to pass flattened response.
So at this point it look like our REST response will always have an envelope element with at least header and root elements inside. Root element will contain requested object or list of objects. If there were referenced objects they will be put into third refs element. TBD: should we group referenced objects by their type?
In all fairness it should be noted that while flattening the response can reduce network traffic it also will increase the load on a server, unless the flattening happens deep in the processing stack, close to the back-end database. If this is impossible (as I suspect it is) I would suggest making this feature configurable on the server. Hopefully we would have JS client library for working with responses which might isolate the user from format details. This library will take care of client-side caching and whatever else we find useful, like building queries