media-types - you really want to do this?
thinking about creating a new media-type for your REST-ful HTTP service?
if at all possible: don't!
if, however, you can't resist, here are some guidelines:
it's all about the client, not the server
design and implement your media-type from the client perspective. in other words, think about what it would take to build a state-engine client application that must consume, parse, understand, and manipulate data within this media-type document.
hint: it's a lot harder to code custom media-type clients than servers.
hypermedia first, data later
the most important aspect of your media-type is the hypermedia links. make sure you work out how clients can find and interpret links in your media-type. you'll need a well-defined set of link relations and clear documentation on which links are for "embedding" data (think the IMG tag) and which links are for navigation (think the A tag).
keep in mind clients need to know which links support which HTTP methods and you'll want to make sure clients know when arguments are to be sent when navigating links (think FORM tags). extra points for figuring out how to let clients know which arguments are required and which are optional. another bonus if you can communicate data types for arguments.
hint: a single argument could be an XML fragment or JSON object. or it can be a name/value pair. what does your media-type support?
data is the easy part
indicating data elements in your media-type is no big deal. you'll need a consistent way to identify the data elements and a clear way for clients to locate them within the media-type. but don't go overboard here. just come up with something simple and general enough to express a wide range of data.
hint: make sure you don't make your media-type so limited that it can only express a small range of data types/collections or you'll fail on the next item in this list.
big and few is better than small and many
keep media-types coarse-grained. the text/html media-type supports a myriad of
applications. if you design a media-type to just support a single object
(application/vnd.customer+xml) you're a weakling. if you've got any skills at
all you should be able to author a single media-type to serve your entire application. if you're
good at this, the media-type will be able to support a wide range of applications - even ones
you haven't thought of yet.
hint: remember, you also need to write a client that fully understands your media-type(s); how to locate links, how to interpret the link relations, etc. you wanna do that for each object in each application? sheesh!
in conclusion
- think client, not server
- hypermedia is important
- data is an afterthought
- narrow-focused media-types are weak
oh yeah, one more bit of advice.
don't do it!