Why do we need a custom media type when using hypermedia links?

Question

I am currently designing an enterprise service that is purely resource oriented. After reading several blogs, books, etc. I believe REST with Hypermedia links is the way to go.

However, one thing that all these blogs and books say is to not use application/xml as the media type when using the hypermedia links in the response. None of them say why except for a generic statement like - plain URIs with no link relation type do not communicate the semantics of URIs to clients.

From what I understood, it is a recommended approach to define your own custom media type and make the client aware of how to read it. But if it is known that the clients connecting to my service will never be browsers, does it matter? Can't I just expose these links in my response with application/xml type?

I was hoping someone here can elaborate more on this.

Answer 1

You don't have to use custom media types. In fact REST tries to discourage people from creating overly specific media types. The ideal is that media types should convey semantic information but not be specific to any particular service.

One problem with application/xml is that it has no standard definition for what a link looks like. Is it

<Link rel="foo" href="/foo">

or is it

<foo href="/foo">

or some other variant? How can your client know how to identify what links exist in a document without using "out of band" knowledge? "Out of band" knowledge is what you want to avoid because it is what causes clients to break when servers make changes and a client cannot protect itself against changes to out of band knowledge.

The other problem with application/xml is that it contains no semantics other than a hierarchy of elements and attributes. Semantics either have to be conveyed by a media type or a link relation. If you use application/xml then you have to use link relations to tell the client how to consume that document.

There can be a nice balance between conveying semantics in link relations and media types. But to be honest, the industry is trill trying to figure out exactly what that balance is and there are lots of people with different opinions on the subject.

I would suggest looking at application/hal+xml. It is the closest thing to generic XML but with link semantics defined.

Answer 2

Here is the best answer I can come up with... I've recently reached out to Dr. Fielding to validate my understanding, but have yet to receive a response. Should he yell at me, I will redact it.

I suspect that, as Darrel Miller has alluded to, the goal should be to avoid creating overly specific types - after all, it has been said:

A REST API should never have “typed” resources that are significant to the client.

I feel that most of the content of the internet regarding Hypermedia as it pertains to REST have essentially violated this principle and steers people in the wrong direction - because they introduce very specific "qualifiers" (as I will refer to them) to their resources.

You see things like application/vnd.com.foo.bar+xml or application/vnd.com.example.thing+json - some people have decided that rather than using the type itself, they will use parameters, e.g. application/xml; someKey=someValue -- this is, in my opinion, no different than qualification. This is, to me, a typed resource.

text/html is the epitome of hypertext for a reason - the browser has a processing directive that it uses to understand this media type. Not just rendering and layout, but robust interaction precedents are set by the HTML specification(s) (e.g. anchor tags cause retrieval, forms can trigger submission with encoding and so on) and it's for this reason that this very generic, highly powerful hypermedia type has allowed all the web pages we use today to come in to existence without any coupling between your browser and the server that provides them - the only thing necessary has been an understanding of what HTML, as a content-type, is.

What does this mean for APIs? It means that creating a content type specific for some resource, some specific URI (or set of them) isn't robustly using hypermedia and likely means you have the kind of client-server coupling that REST is trying to avoid. It also means that application/xml and the like are anemic - they have parsing directives but not processing directives. A well-designed REST API will have a much more generic hypermedia type, not created for a particular resource, but rather to clearly define the processing directives that potential clients must understand in order to participate.

The interesting - and admittedly probably controversial - thing is that text/html has a lot of that already - why not use it? The fact that our API consumers want something other than HTML (e.g. they think JSON or XML formats are a panacea) is really due to an inherent misunderstanding of what it means to have a hypermedia-driven application engine - namely it's that the processing directive of the representation should be rather generic. Granted, you can do this with XML, just by having your API define a clear set of elements and what they mean. The part about using HTML was just to illustrate a point.

Aspiring REST APIs, even with a rich set of hyperlinks expressing state transitions through resources, can - and it seems most often do - fall short of that extensible, long-living architectural style that REST is really about.