I finally understand how media types should be used in REST<link>. I have not struggled as much to understand any of the REST constraints and principles as much as I had to understand the proper use of media types. Even HATEOAS<link> didn’t cause me such difficulty in understanding (though the ahh!! moment when I finally undetstood HATEOAS is still fresh in my mind). After the insight into HATEOAS, I felt I had mastered REST and went on to design a real application based on REST principles. When I started on the design of the application , I glided through the steps <link> of resource identification , methods supported at each URI’s but soon hit a snag when it came to the use of media types. The major problem or confusion I faced was the increasing number of media types that were getting defined in our application. I then posted a question here<link> and also exchanged few emails with experts<subbu> in the field hoping to understand where or what I was doing wrong. Even though I did get some really good responses to both my question and through emails, I still couldn’t get my head around the confusion. The main reason I never got around to understanding is due to the fact that I had a totally wrong assumption on the role of media types. After spending quite some time researching, trying to figure out where and what I was doing wrong, I think I might have finally found the missing link.
With this post, I hope to get across my understanding of media types and try to clarify the role of media types in REST for those who might have got into similar situation.
First some background, one of the goals of our team was to replace a legacy (proprietary) communication mechanism with standards based communication system. We choose HTTP and also made a conciouse decision to base our architecture on RESTful principles, and thats when we started looking at media types. Our initial understanding of the role of media types were that media types are used to describe the representation of the resources in lieu of a schema language i.e. we thought that each resource should have a media type which defines the processing model, the applicable methods on the resources and also the structure details of the resource representation. This led to us defining a media type for each resource in our application and finally to the realization that we were doing something wrong.
Recently, I came across the statement “media type for helping tune the hypermedia engine, schema for structure” <link> in a blog entry by Jim Webber. I then found this presentation<link> by Ian Robinson of Thoughtworks<link>. This presentation is one of the best that I have come across that provides a very clear understanding of the roles and responsibilities of media types and schema languages (the entire presentation is a treat and I highly recommend for all). Especially lookout for the slides titled “You’ve Chosen application/xml, you b*st*rd.” and “Custom media types”. Ian clearly explains the different roles of the schemas and the media types. In short, this is my take away from Ian’s presentation:
A media type description includes the processing model that identifies hypermedia controls and defines what methods are applicable for the resources of that type. Identifying hypermedia controls means “How do we identify links?” in XHTML, links are identified based on <a> tag and RDF has different semantics for the same. The next thing that media types help identify is what methods are applicable for resources of a given media type? A good example is ATOM (application/atom+xml) specification which gives a very rich description of hyper media controls; they tell us how the link element is defined? and what we can expect to be able to do when we dereference a URI so it actually tells something about the methods we can expect to be able to apply to the resource. The structural information of a resource represenation is NOT part of or NOT contained within the media type description but is provided as part of appropriate schema of the actual representation i.e the media type specification won’t necessarily dictate anything about the structure of the representation.
So what does this mean to us? simply that we dont need a separate media type for describing each resource as described here<link>. We just need one media type for the entire application. This could be a totally new custom media type or a custom media type which reuses existing standard media types or better still, simply a standard media type that can be reused without change in our application.
Now, armed with this knowledge, I do hope to progress smoothly in our design and as Jim says, “media type for helping tune the hypermedia engine, schema for structure” is going to be my mantra too.
I finally understand how media types should be used in REST. I have not struggled as much to understand any of the REST constraints and principles as much as I had to understand the proper use of media types. Even HATEOAS didn’t cause me such difficulty in understanding (though the ahh!! moment when I finally undetstood HATEOAS is still fresh in my mind). After the insight into HATEOAS, I assumed that I had mastered REST but my fallacy was exposed when I went on to design a real application based on REST principles. When I started on the design of the application , I glided through the steps of resource identification , supported methods, etc… but soon hit a snag when it came to the use of media types. The major problem or confusion I faced was the increasing number of media types that were getting defined in our application. I then posted a question here and also exchanged few emails with experts in the field hoping to understand where or what I was doing wrong. Even though I did get some really good responses to both my questions and through other channels, I still couldn’t get my head around the confusion. The main reason I never got around to understanding is due to the fact that I had a totally wrong assumption on the role of media types. After spending quite some time researching, trying to figure out where and what I was doing wrong, I think I might have finally found the missing link.
With this post, I hope to get across my understanding of media types and try to clarify the role of media types in REST for those who might have got into similar situation.
First some background, one of the goals of our team was to replace a legacy (proprietary) communication mechanism with standards based communication system. We choose HTTP and also made a conscious decision to base our architecture on RESTful principles, and thats when we started looking at media types. Our initial understanding of the role of media types were that media types are used to describe the representation of the resources in lieu of a schema language i.e. we thought that each resource should have a media type which defines the processing model, the applicable methods on the resources and also the structural details of the resource representation. This led us to defining a media type for each resource in our application and finally to the realization that we were doing something wrong.
Recently, I came across the statement “media type for helping tune the hypermedia engine, schema for structure” in a blog entry by Jim Webber. I then found this presentation by Ian Robinson of Thoughtworks. This presentation is one of the best that I have come across that provides a very clear understanding of the roles and responsibilities of media types and schema languages (the entire presentation is a treat and I highly recommend for all). Especially lookout for the slides titled “You’ve Chosen application/xml, you b*st*rd.” and “Custom media types”. Ian clearly explains the different roles of the schemas and the media types. In short, this is my take away from Ian’s presentation regarding media types:
A media type description includes the processing model that identifies hypermedia controls and defines what methods are applicable for the resources of that type. Identifying hypermedia controls means “How do we identify links?”, in XHTML links are identified based on <a> tag and RDF has different semantics for defining links. The next thing that media types help identify is what methods are applicable for resources of a given media type? A good example of these can be seen in the ATOM (application/atom+xml) specification which gives a very rich description of hyper media controls; they tell us how the link element is defined? and what we can expect to be able to do when we dereference a URI so it actually tells something about the methods we can expect to be able to apply to the resource. The structural information of a resource represenation is NOT part of or NOT contained within the media type description but is provided as part of appropriate schema of the actual representation i.e the media type specification won’t necessarily dictate anything about the structure of the representation.
So what does this mean to us? simply that we dont need a separate media type for describing each resource as described here. We just need one media type for the entire application. This could be a totally new custom media type or a custom media type which reuses existing standard media types or better still, simply a standard media type that can be reused without change in our application.
Now, armed with this knowledge, I do hope to progress smoothly in our design and as Jim says, “media type for helping tune the hypermedia engine, schema for structure” is going to be my mantra too.
