REST HATEOAS: How to determine and set media-type while browsing links?

Question

I was going through what was described as an example of a good REST API. A GET was sent on the base URI and with a media-type that was already known to the client somehow (which is fine, as per REST principles).

 To server:

 GET /
 Host: xrgy.cloud.sun.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cloud+json
 X-Compute-Client-Specification-Version: 0.1

 From Server:

 HTTP/1.1 200 OK
 Content-Type: application/vnd.com.sun.cloud.Cloud+json
 Content-Length: nnn

 {
   "implementation_version": "597",
   "vdcs": [
     {
       "name": "XRGY Virtual Data Center",
       "uri": "/vdc"
     }
     {
       "name": "R&D sandbox"
       "uri": "/sandbox"
     }
   ],
   "uri": "http://xrgy.cloud.sun.com/",
   "specification_version": [
     "0.5"
   ]
 }

But what I got stuck in was how the client set the media-type for the subsequent request. I understand that the client got the URI for the next request from the previous response. But where did it get the media-type from ? If it is prior knowledge to the client, then how do clients typically maintain such URI:media-type mappings ? It seems I am definitely missing out on some basic knowledge here. Here is the subsequent request sent with a media-type of : application/vnd.com.sun.cloud.Vdc+json !

To server:

 GET /vdc
 Host: xrgy.cloud.sun.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Vdc+json
 X-Compute-Client-Specification-Version: 0.1

From server:

 HTTP/1.1 200 OK
 Content-Type: application/vnd.com.sun.cloud.Vdc+json
 Content-Length: nnn

 { 
   "name" : "XRGY Virtual Data Center",
   "uri" : "http://xrgy.cloud.sun.com/vdc",
   "vm_templates" : "http://cloud.sun.com/resources/template-cat.json",
   "addresses" : [
     {
       "name": "144.34.100.199",
       "uri": "/addresses/144.34.100.199",
       "ip_address": "144.34.100.199"
     }
   ],
   "cluster" : {
     "name" : "ROOT",
     "uri" : "/vdc/",
     "tags" : [ ],
     "volumes" : [ ],
     "clusters" :  [
     ]
     "tags" : [ ],
     "controllers" : [
       "start" : "/vdc/ops/start",
       "stop" : "/vdc/ops/stop",
     ]
     "vnets" : [
       {
         "name": "vnet1",
         "uri": "/vnets/10.31.145.0",
         "netmask": "255.255.255.0",
         "network": "10.31.145.0"
       }
     ],
     "vms": [
       {
        * SNIPPED *
       }
     ]
   }
 }

I have seen other examples where the media-type is also part of the links in the response, such as this following response and i can understand that.

201 Created
Content-Type: application/vnd.bank.org.transfer+xml;charset=UTF-8

<transfer xmlns="urn:org:bank:accounts">
    <link rel="self"
          href="http://bank.org/transfer/XTA8763"/>
    <link rel="http://bank.org/rel/transfer/from"
          type="application/vnd.bank.org.account+xml"
          href="http://bank.org/account/AZA12093"/>
    <link rel="http://bank.org/rel/transfer/to"
          type="application/vnd.bank.org.account+xml"
          href="http://bank.org/account/ADK31242"/>
    <link rel="http://bank.org/rel/transfer/status"
          type="application/vnd.bank.org.status+xml"
          href="http://bank.org/check/XTA8763"/>
    <id>transfer:XTA8763</id>
    <amount currency="USD">100</amount>
    <note>RESTing</note>
</transfer>

found a very good answer for a part of this qn in [another place](http://stackoverflow.com/a/9639345/1733060) — 2020, Apr 15 '13 at 21:35

score 3 · Accepted Answer · answered Apr 03 '13 at 21:19

Simply put, yes, the client needs to have some a priori knowledge of the media types involved. Since the client actually sets the media types that it can consume. Since the client only understands "some" media types, if it sends a request with a media type that the application does not support, then the client is pretty much out of luck.

Since, in the the real world, we try to not have clients make blind calls to services returning payloads that they don't understand, the client will have some fore knowledge of the payloads involved, especially very specific types (vs plain/text or application/xml).

Finally, recall that the media type will effectively tell you the SYNTAX of the payloads but not how to interpret the payloads. Those semantics your client will have to know up front as well, so the burden of having an initial understanding of a media type is in fact not particularly a barrier to participation, it's just a fact of life.

score 1 · Answer 2 · answered Apr 03 '13 at 20:39

1

Clients are responsible for telling servers what kind of response they understand/prefer. That is what the Accept header indicates. Servers respond with content that attempts to satisfy the client's request. The Content-Type header indicates what is actually returned. Ideally, the value of this header is the same as that of the Accept header.

See sections 14.1 and 14.17 in RFC 2616.

In your example, the client author probably is injecting knowledge into the client and this is not truly a 100% RESTful client.

answered Apr 03 '13 at 20:39

David Peden

17,596
6
52
72

I have no confusion on the meaning of Accept header in the Request and Content-type header in the response. Sorry, if my question used 'content-type' in places where 'Accept header' shd have been used. Have corrected this in the question now and I now use 'media-type' in general. My question is more pertinent when you consider that that REST API is [mentioned](http://stackoverflow.com/questions/297005/what-is-the-gold-standard-for-website-apis-twitter-flickr-facebook-etc) as meeting the GOLD standard. So, I am guessing it should promote a good RESTFUL client !? – 2020 Apr 03 '13 at 21:00
Cool, given that confusion I put in the boiler plate response. As far as an agreed-upon gold standard, I don't know that there is one. That list from your linked post merely mentions the most commonly used APIs, not necessarily the most RESTful. It is reasonable for clients to be aware of the general content type that servers can offer. At the end of the day, there is always a single, well-known endpoint from which all subsequent flows originate. That the client example you posted switches Accept headers mid-flow with zero indication to do so suggests hard-coded knowledge. – David Peden Apr 03 '13 at 21:15
And you say such knowledge makes the client not so ReSTful ? Will's answer is suggesting that such knowledge is inevitable, unless the server limits itself to standard media-types. – 2020 Apr 03 '13 at 21:28
No, I didn't say that it was not RESTful. I agree with Will's answer. A client must understand the semantics of a response in order for the agreed-upon structure to be valuable. – David Peden Apr 03 '13 at 21:40

REST HATEOAS: How to determine and set media-type while browsing links?

2 Answers2