6

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.

Sharat
  • 61
  • 2

2 Answers2

6

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.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 1
    +1 good post - though I'd argue that the problem really isn't that `application/xml` doesn't contain a 'standard' link type -- really, that's a concern of your API specification. Clients have to implement whatever processing directive you decide on. I think the *real* problem, as I've said in my response, is that nobody seems to be equipped to come up with processing directives on par with the flexibility afforded by `text/html` (which leaves me to wonder, why don't we use HTML for our APIs? Lots of open-source code, and clients don't have to actually render anything. Food for thought.) – Doug Moscrop Jun 16 '13 at 22:38
  • Also, I disagree with your out-of-band knowledge point. The *format* is not the issue here - otherwise I could argue that HTML requires "out of band" knowledge as to what an anchor element is, or what an input element is. That stuff is defined, clearly, as a basis of what the processing model is for HTML. The same should hold true for your API -- but it should be flexible. JSON/XML/YAML aren't a problem because their format is flexible, they're a problem because they have no well-defined directive for hypermedia controls. (those are more than *just* hyperlinks). – Doug Moscrop Jun 17 '13 at 00:10
  • 1
    @Doug Both Jon Moore and Mike Amundsen have a number of articles/videos on using xhtml for APIs. It is quite a common approach. HTML does not require out of band knowledge for links because the Content-Type header points to text/html and the IANA registry points to the HTML spec which defines the link syntax. The application/xml spec does not. – Darrel Miller Jun 17 '13 at 11:35
  • I'll check them out - thanks! I didn't know it was common, but regardless I suspect that there is no shortage of people who would double-take such a concept (especially if it's coming from a non-authoritative source or otherwise nobody such as myself) with a kind of "What? That's layout information for the browser!" – Doug Moscrop Jun 19 '13 at 15:53
4

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.

Community
  • 1
  • 1
Doug Moscrop
  • 4,479
  • 3
  • 26
  • 46
  • I phrased my answer badly. It's not REST that has any opinion on how specific your media type is, it is more the REST community have a fear of an explosion of media types. I am less concerned about specific media types and more concerned about people creating media types that are only useful for one API. I want to see many media types created that can be re-used across lots of APIs. – Darrel Miller Jun 17 '13 at 12:58
  • 1
    I think you are over-interpreting what Fielding meant by API should never have typed resources. The paragraph goes on to say 'The only types that are significant to a client are the current representation’s media type and standardized relation names.' Media types are types. What I believe fielding is saying there if you do `GET /Customer` and get application/xml back you can't make the assumption that there is a Customer type serialized in that XML. – Darrel Miller Jun 17 '13 at 13:02
  • In general I agree with what you are saying. I would avoid using the term "processing instructions" because application/xml does actually define that concept. I think hypermedia controls is a much better term for what is missing in app/xml. However, HTML is not the only format that has the capability to create RESTful systems. Collection+json and HAL are two fairly new formats that when combined with link relations can be quite effective. – Darrel Miller Jun 17 '13 at 13:07
  • I'm not sure about that - if you over-specify the media type of resources, then you're effectively creating a statically typed interface, are you not? HTML is the epitome of hypertext and REST because it is *the* uniform interface of the web. I would not want my browser to have to understand "application/bank-account" any more than I would "application/customer". Make sense? The hypermedia controls in HTML are very, very general. I believe that we likely want some subset within a particular application domain, but not at a resource level. – Doug Moscrop Jun 19 '13 at 15:46
  • I agree, you can't make the assumption that you have a `customer` inside your `application/xml` -- but specifically because you shouldn't have to know that it *is* a customer. There should be hypermedia controls present on the representation, based on either HTML, or whatever your API specified, that describe the ability to query, for example, among other state-transitions as made available by hyperlink relationships. – Doug Moscrop Jun 19 '13 at 15:48
  • I certainly appreciate that HTML is not the only format to create a hypermedia system - it just happens to be a fairly rich language that defines hypermedia controls satisfying most interactions with as little specificity as possible - hence our ability to use HTML to communicate as we are, as well as log in to Facebook (if one is so inclined), bank on-line, etc. – Doug Moscrop Jun 19 '13 at 15:50
  • HTML is not the uniform interface, HTTP is. HTML has type semantics in the domain of text documents. e.g. h1, head, body, p, br, table, etc. The web wouldn't work without `text/css`, `x-application/x-www-urlencoded-form`, `image/png`, etc. These are all precisely defined "types". – Darrel Miller Jun 19 '13 at 15:56
  • Yes, I agree with you that Html is generic enough to represent an interface to huge range of application domains, on the read side. However, I find HTML forms quite limited in their ability and generally require JS to augment their capability to something decent. Supporting JS on a client is not a trivial task. – Darrel Miller Jun 19 '13 at 16:01
  • So HTTP is a uniform interface - I see that after revisiting the dissertation. However, it is still the processing directives of HTML that instruct the client to submit a `urlencoded-form`, no? So my point is not that there is only one *type* within the web, (note: I disagree about the web not working without `text/css`) but that those types are not defined around resources. It's the over-specificity that I'm disagreeing with, not that I believed we had a "uniform hypermedia language" or something like that. – Doug Moscrop Jun 19 '13 at 17:14
  • Can you cite an example of HTML forms being limited in the manner you're purporting? I don't feel like I've ever encountered an HTML form that failed to convey what it was I could do, in the context of a hypermedia control. Granted, using pure forms to represent state transfer piece by piece tends to be boring or even awful for users, but that seems irrelevant when discussing the actual mechanism by which the server communicates the availability of said hypermedia controls. The debate here is whether specificity needs to happen at a resource level. – Doug Moscrop Jun 19 '13 at 17:16
  • I take back what I said about HTTP being the uniform interface. And yes hypermedia is one part of the uniform interface. My point is just that HTML is only one media type and not something that we should be overly dependent on. – Darrel Miller Jun 19 '13 at 18:04
  • 4
    Agreed - I've checked out your blog and I will continue to do so. It's funny because I engaged in a side conversation with a colleague and agreed that HTTP can be thought of as the uniform interface of the WWW as an application on top of the internet. Either way I think we deserve a new Stack Overflow badge: [Discuss REST Without Arguing or Insulting Each Other] Cheers :) – Doug Moscrop Jun 19 '13 at 18:39