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>

Answer 1

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.

Answer 2

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.