title: metainformation in REST: Envelope VS HTTP Header
body: <p>While retrieving a resource representation from a server, it can be necessary to obtain some additional information. The information I mean refers <em>specifically</em> to the resource, such as a peculiar error message ("the requested dog can't be retrieved because a cat crossed the road!").</p>
  
  <p>I made a research and I'm feeling a little confused about the most <strong>RESTful way</strong> to do it (it goes without saying I'm referring to the HTTP implementation of REST). Honestly, I feel there's no "standard" way to adopt but I'd like to hear different opinions.</p>
  
  <p>Here's mine:</p>
  
  <p><strong>using HTTP Header</strong> - the main reason to do it is because HTTP already provides an envelope, so why to inject a new custom envelope inside the protocol's one? In addition, HTTP is an <em>application</em> protocol and it's supposed to support application interactions. However, pushing new information into the Header section has two drawbacks: first, you're going to include custom stuff and this does not comply too much with the "uniform interface" recommendation.
  In addition, by looking at the standard Headers you'll see that the vast majority of them relate to the connection and information exchange (<code>Accept</code>, <code>Connection</code>, <code>Forwarded</code>, <code>Host</code>, <code>User-Agent</code> etc.) and refer to the payload in a very <em>agnostic</em> way (<code>Content-Type</code>, <code>If-Match</code>, <code>Etag</code>, etc.). It seems to be an inappropriate context for information specific to the resource.</p>
  
  <p><strong>using an envelope</strong> - this strategy is good for two reasons: it is very flexible and this is the place the 99% of clients are used to look at for metainfo. From a theoretical point of view, we can say that the envelope containing the object <em>is</em> the representation of our resource. When asked for a car object, a server is free to provide the most meaningful representation for that request. The bad thing is that it sounds so similar to the SOAP approach that opposes completely to REST.</p>
  
  <p><strong>a mediation</strong> - my idea is to be pragmatic: don't abuse the Header customization and use the ones you have instead. If you need to implement HATEOAS, go with the <code>Link</code> Header. If you need to represent your resource for caching go with <code>ETag</code>. If you need an heavy customization, use an envelope as a resource and provide the metainformation you need in an envelope section.</p>