2

While retrieving a resource representation from a server, it can be necessary to obtain some additional information. The information I mean refers specifically to the resource, such as a peculiar error message ("the requested dog can't be retrieved because a cat crossed the road!").

I made a research and I'm feeling a little confused about the most RESTful way 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.

Here's mine:

using HTTP Header - 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 application 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 (Accept, Connection, Forwarded, Host, User-Agent etc.) and refer to the payload in a very agnostic way (Content-Type, If-Match, Etag, etc.). It seems to be an inappropriate context for information specific to the resource.

using an envelope - 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 is 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.

a mediation - 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 Link Header. If you need to represent your resource for caching go with ETag. If you need an heavy customization, use an envelope as a resource and provide the metainformation you need in an envelope section.

MaVVamaldo
  • 2,505
  • 7
  • 28
  • 50

2 Answers2

3

Including metadata in the content ("envelope") seems to be easier to process and harder to miss. On the other hand, HTTP headers can be added to an existing service without breaking backward-compatibility.

If there are no strict requirements, I would choose what is more convenient. A pragmatic way looks good to me.

pkalinow
  • 1,619
  • 1
  • 17
  • 43
  • thank you very much for your answer. I agree with your considerations on pragmatism, but my question was more focused on the model aspect. I mean, I know the advantages and drawbacks of using headers and envelopes using web instruments. But, what is the *right* thing to do? Why? – MaVVamaldo Nov 28 '16 at 11:07
2

All three options are fine. In fact, you haven't suggested a fourth: embed the metadata at or beneath the model data (rather than in an envelope around it, as suggested in your third choice).

Your aversion to an envelope because it is SOAP-like is understandable, but the non-RESTful-ness of SOAP is more to do with the hidden transmission of the real method/caching/date metadata in the envelope rather than in the HTTP layer, instead of the mere presence of an envelope. As you point out, the envelope becomes part of the representation of your resource, and as long as your media type is described properly, that's fine!

Personally, I would put as much in standard HTTP headers as I could, and everything else in the representation (outside or adjacent to the model data, I don't care). I would not use custom headers. This lines up with your third choice, as best as I can tell.

Nicholas Shanks
  • 10,623
  • 4
  • 56
  • 80