REST Media Type Proliferation

Question

I took a look at this question that seeks to address the issue of REST media-type explosion. One of the suggestions was to have a media-type that describes a collection of anything. So for example, we could have an application/vnd.collection+json which is a collection with well-defined semantics that can hold a list of references to other resources:

{
    "size": "3"
    "elements": [
         { "href" : "http://my.api.com/resource/1" },
         { "href" : "http://my.api.com/resource/2" },
         { "href" : "http://my.api.com/resource/3" }
     ]
}

I know an option to alleviate chattiness is to include embedded representations of resources. How would a "generic" media-type for lists accomplish that? Don't the semantics of the list change based on which embedded resource is inside it? This is especially relevant if embedded resources have different processing-rules (which would ideally be conveyed by the media type). Would be alright in this case to allow in-band information that describes the media type of the embedded resource? For example we could have application/vnd.collection+json for both links and embedded resources that do something like this:

{
    "size": "3"
    "element-content-type": "application/vnd.link+json" 
    "elements": [
         { "href" : "http://my.api.com/resource/1" },
         { "href" : "http://my.api.com/resource/2" },
         { "href" : "http://my.api.com/resource/3" }
     ]
}

and if it contains an embedded resource:

{
    "size": "3"
    "element-content-type": "application/vnd.resource+json" 
    "elements": [
         { 
             "id": "1"
             "name": "Cool Resource" 
         },
         { 
             "id": "2"
             "name": "Awesome Resource" 
         },
         { 
             "id": "3"
             "name": "Super Awesome Resource" 
         }
     ]
}

The assumption is that application/vnd.link+json and application/vnd.resource+json have been documented as well.

Vivin Paliath · Accepted Answer · 2015-02-11T15:59:28.757

I thought about this a little bit more, and I think it is actually OK to include the content-type like that. The reason is, we already do this. In HTML the script tag has a type attribute that can be application/javascript or application/vbscript (for example). The provides the browser a hint as to how to process the content of that tag. Similarly, I think the content-type in the above example achieves the same purpose: it tells the client how to process the elements in the collection.

I wanted to update this answer some more. It appears that another way to do this is to use a rel. At least, this is how HAL does it. You can create a namespaced rel with a curie so that you end up resolving the rel to a URL that points to documentation about that resource. This way you have access to the documentation and that should tell you all you need to know about the resource(s).

REST Media Type Proliferation

1 Answers1