The subject of media types has been glossed over in some of our recent blogs and screencasts. In this blog I’d like to focus on what media types are and give some basic guidelines for using them in your RESTful web services.
A media type is a two-part identifier for file formats on the Internet. Some examples of very common media types are:
- text/xml
- text/html
- audio/mpeg
- video/mp4
- image/jpeg
A list of registered media types is made available on the web by the Internet Assigned Numbers Authority (IANA). So how does this relate to RESTful web services? As you already know RESTful web services are focused around resources, and service clients interact with those resources through representations. Every representation of a resource is a media type.
Here are a few guidelines regarding how you should represent the resources in your web services using media types:
Whenever possible you should use existing media types to represent your resources.
This will open your web service up to many more clients, and allow for much easier integration. It makes perfect sense. If you had a resource that was a person and you wanted one representation of the resource to be a picture of the person, would you send back that picture using the “image/jpeg” media type or would you make up your own image format and use that? I think the answer is pretty obvious.
One commonly used media type in RESTful web services is the ATOM Syndication Format (application/atom+xml). ATOM was essentially designed as an improved format for web feeds. But its flexibility has made it a great media type for representing resource collections. By using the ATOM media type to represent your collection resources, you immediately open your service up to a huge range of clients that already know how to parse ATOM XML.
Ensure that your media types accurately represent your resources.
So I’m going to pick on one of our own previous blog postings. In the last blog on HATEOAS we used the following request / response example:
Client Request:
GET /dictionary/happy HTTP/1.1 Accept: application/xmlService Response:
Content-type: application/xml<?xml version="1.0" encoding="UTF-8"?>
<entry>
<word>happy</word>
<part-of-speech>adjective</part-of-speech>
<definition>delighted, pleased, or glad, as over a particular thing</definition>
</entry>So here our client has asked for a resource represented using the ‘application/xml’ media type. And our service has responded with the representation in XML format. You may wonder: “What’s the problem? ‘application/xml’ is a valid and common media type.” That it is, but unfortunately, if I go and read the specification for the ‘application/xml’ media type I will be able to parse the response above, but I won’t have any idea what it means.
The same would apply if I had sent back ‘application/json’. So what is the best thing to do? First, check the registered media types to see if there is a public and widely used representation for dictionary entries that meets your needs. If you find one that nearly meets your needs, hopefully you can extend it. If you don’t find one, then you’ll have to create your own media type. Here’s how the previous request might look if I had used a custom media type for a dictionary entry:
Client Request:
GET /dictionary/happy HTTP/1.1 Accept: application/dict-entry+xmlService Response:
Content-type: application/dict-entry+xml<?xml version="1.0" encoding="UTF-8"?>
<entry>
<word>happy</word>
<part-of-speech>adjective</part-of-speech>
<definition>delighted, pleased, or glad, as over a particular thing</definition>
</entry>As you can see, the data returned here is the same. The key difference is in the ‘Content-type’ header. The ‘application/dict-entry+xml’ media type would be well-defined and clearly inform the client of how to interpret the response.
Ensure all your media types are well documented and publicly available.
This is not much of an issue if you use a registered media type to represent a resource. However, if you are using custom media types or extending a registered media type, it is imper