Custom Media types in REST

Though most of REST was easy to grok, the HATEOAS constraint and the use of media types in REST posed a huge learning curve for me. So while deciding whether to use custom media type or stick with application/xml or use a standard media type, I had a hard time to choose. What I realized after many months of wading through articles , posting questions in discussion forums, trying to write clients against different respresentations is that though there are standard media types out there (text/html, atom etc.) , there are cases where just standard media types won’t suffice to application’s requirements. In these scenarios, defining a custom media types to capture and convey a consistent vocabulary to suit an application domain is not only good but IMO, a necessity if we want to get all the benefits of REST.

For our RESTful application, we started off defining a domain specific XML vocabulary but ended with a generic XML vocubulary to describe resources. One of the major goal of vocabulary definition was to have the ability to describe all resources in uniform and consistent manner. Initially we started designing the vocabulary around the semantics of each resource and found out soon that it was harder to mantain. We then decided to make a generic “resource” vocabulary i.e. the vocabulary was aimed at to be applicable to a large set of resources as possible. We also based our design on the needs of the client rather than around the specific resource. The design considered that anything exposed by our application is a resource which can be linked and provides links to other relevant resources. We have also tried to follow the basic software engineering principle of “Applying the software engineering principle of generality to the component interface”.

As per REST, a Resource is defined as:

“The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource”

Thus a resource is the fundamental building block in a RESTful system. A resource can have properties of any type (xsd: or custom) and can also contain resources. Based on these assumptions, we have come up with a generic XML vocabulary to describe all the resources in our system. I will post the vocabulary in my later posts.

Advertisement