Media Types, Plumbing and Democracy

My blog post on media types is now 15 pages long in print with all the comments - http://bit.ly/6ARAgP

2 months, 1 week ago by sallamar on Twitter

JAX-RS can route based on media type. That is not the problem. The problem resides in the fact that most (all?) JAX-RS implementations are built on top of a servlet container. Each web deployment is its own classloader and thus you can’t version classes within it. I don’t know of any servlet implementations that allow you to bind different web deployments to the same URL scheme.

2 months, 1 week ago by Bill Burke on Wordpress

I don’t think your PO/Album example is a good one. A better one would be an Oracle Financials PO vs. a SAP PO. Or a Saleforce.com contact vs. a Thunderbird contact. If a client receives a URL how is it supposed to ask for, or find out a specific XML format exists? Conneg + custom media types is one way. Links are another. One causes an explosion of media types, the other an explosion of links . no? I don’t have time now, but I’ll blog more about what I mean by this.

As for versioning, I was all for using a version tag within a media type along with conneg. Now, I’m not so sure, but, not because of this blog post. In Java land, with the current tools available, it would be very hard to implement a common URL scheme that served up different versions of the same application using conneg. The problem being that you’ll probably have different versions of the same Java class that process this data. Using hateoas pretty much can hide any complicated URL scheme that proliferates because of applicationv versioning. ... See all content Hide content

2 months, 1 week ago by Bill Burke on Wordpress

Interesting discussion about media types in RESTful apps http://j.mp/8dHfuE

2 months, 1 week ago by ferdy on Twitter

A small variation I’ve had success with is to stick with standard media types but to add link headers with further type (or at least type-like) information.

In described_routes (on hold unfortunately while the URI Template standard gets redrafted), the type identifiers come in the form of URIs that point to URI Template-based metadata, making the application nicely self-describing and facilitating the discovery of similar and related objects. ... See all content Hide content

2 months, 3 weeks ago by Mike Burrows on Wordpress

Interestingly, there are several who would disagree with your interpretation. Having watched/participated in this debate a few times, I remain agnostic of either interpretation.

It is better to go beyond the terminology and interpretations and look at the problem being solved and its viability. If you’re convinced that your XML needs a new media type, just make sure that there are no use cases or requirements for your plumbing to differentiate requests or responses based on media types. Some areas to watch out include (a) logging, (b) proxy level routing, (c) rate limiting, and (d) metrics. By the way, some of these will be problematic when you extend media types for versioning. That’s why I would be more careful about betting heavily on custom media types for versioning. ... See all content Hide content

2 months, 4 weeks ago by subbu on Wordpress

Subbu,

I don’t think Dr. Fielding intended for the first option to be the “correct” understanding of how to use mime types. In his blog post of last year titled REST APIs must be hypertext-driven he writes:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

I think his assertion that A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources argues for the use of custom mime types. Otherwise it would have been more correct to say “choosing the media types”. Mind you you could disagree with my attempt to equate media types with mime types.

The question is “What is a standard mime type?” That is followed closely by, “Between whom must the standard be recognized?” If the answer to the second question is, “Those who care about the API”, then the answer to the first is, “What ever those who care about the API say it is.”

Nevertheless, I disagree that the “cost” of custom mime types is (necessarily) high.

First of all, all you have to do is say, “documents that conform to this schema/design/format are know as text/com.example.coolness+json” and you’re done.

While registration may be desirable if you have a sufficiently large audience for your application, its hardly a requirement (and hardly a likely situation to exist at its inception). If you use something like application/com.example.coolness+json or application/com.example.coolness+xml then you should reasonably expect a generic JSON or XML parser to correctly parse the representation as XML, if that is necessary.

Second, lets think about all the costs. What do you think would be the development cost of web browsers if we didn’t have text/html but rather the more “standard” application/sgml. I imagine it would make everything a lot less pleasant for the same reasons that simply using application/xml would… you would have to parse the entire document just to find out if you understood it or not. Similarly for clients that consume your API, knowing what its getting without having to parse everything will be hugely beneficial, especially if it needs to perform different behaviour based on receiving different types.

It will never be the case that any user agent requesting your resource will know nothing about the structure of your resources; that would it completely useless. Even if you parsed a schema and knew that this thing was a URI and that thing was a string, you could not know how to use them. As such it is reasonable to assume that what ever user agent is requesting your resource will be a client designed to handle your mime type(s). Even if you’re building a web application, one can (and should IMHO) consider the browser and the XHR object it provides as part of the transport layer and the JavaScript code you write to deal with your resources is the “real” user agent.

Finally, there is no need, indeed you probably should not, be stingy with your handling of mime types. The request should include an accepts header. If you find application/com.example.coolness+json then by all means, send your resource using that mime type, but if all you get is application/json then send that mime type. You may even elect to include schema information for the generic mime type that would be unnecessary for the custom type.

So in conclusion, my opinion (for what little its worth), is that you should create as many mime types as you feel is necessary (although try to use or extend existing mime types if you can). If your application is only used by a handful of people, then there is not even any reason to register your mime type as those who care about it will already know what to do with it. If, however, your application becomes wildly popular, or more generally useful, then by all means please register the mime type.

They are, after all, just strings. They’re not going to hurt anyone. ;) ... See all content Hide content

2 months, 4 weeks ago by Adam on Wordpress

Versioning is not cheap. In any case, as we debated in the past versioning by media types does not fly for non-XML types.

Regarding your question, penalty of using custom media types for the sake of communicating semantics to custom application code is high. It goes up with the size of the service.

2 months, 4 weeks ago by subbu on Wordpress

Hi Peter,

I gave namespace as an example for code to figure out a way to learn about the XML. For versioning, using version identifiers in URIs is a safe bet.

If the key motivation is to communicate application semantics, then there are cheaper ways. Sometimes, the client "just knows".

2 months, 4 weeks ago by subbu on Wordpress

Media Types and Plumbing: On the other hand, most of the HTTP plumbing (e.g. proxies and firewalls), and HTTP plumb... http://bit.ly/6C424e

2 months, 4 weeks ago by SeattlePlumbing on Twitter