Re: [rest-discuss] Link relations [was: A media type for case files, dossiers and documents]
I get everything you are saying..finally thanks to a few of you that set me clear on this whole media-type issue.
I am however having a hard time thinking about telling clients that they basically need to parse html to use my API. I much rather say "for /orders, you get this chunk of xml back with these potential elements.. parse it to get the data you need". Or in JSON. As I use Java/JAX-RS with Jersey, it handles automatically turning my objects into either xml or json, whatever the Accept header specifies. Anyway, for my own learning, it is good to know what you said, and it does make sense. However, it seems odd to me to return things in HTML as opposed to xml or json, when it's just chunks.. that is, a user places 100 orders over 3 months, then comes in and asks to see a history of orders. I return an xml chunk with their 100 orders and related info. That seems perfectly fine to provide in xml or json, allowing any client to parse the response as they see fit. I would obviously have some sort of api doc that would explain the response.
--- On Thu, 12/2/10, Eric J. Bowman <eric@...> wrote:
From: Eric J. Bowman <eric@...>
Subject: Re: [rest-discuss] Link relations [was: A media type for case files, dossiers and documents]
To: "Kevin Duffey" <andjarnic@...>
Cc: "Rest Discussion List" <firstname.lastname@example.org>, juergen.brendel@...
Date: Thursday, December 2, 2010, 10:32 PM
Kevin Duffey wrote:
> Valid point. I am not sure what media type would fit then. I am
> trying to follow the HATEOS design, I have an entry point that
> returns some links based on credentials, from there a client would
> use those to make calls to any of my resources, and each response
> would return a relevant chunk of XML or JSON with links for each
> resource accessible at that point (for example GET /orders/id would
> return a specific order along with one or more links that can be used
> to operate on the order).
I've never seen an order-processing system that couldn't be modeled as
HTML. In fact, I've rarely seen an order-processing system that wasn't
HTML. In OOP terminology, the goal is to distribute not your objects,
but your object interfaces. REST says, make those object interfaces
uniform. Which means participants have a network-based shared
understanding of your state transitions (links, forms), IOW, a self-
It's perfectly acceptable to model your data as JSON or as XML (bearing
in mind that schemas are an orthogonal concern). The trick is to
create an HTML interface for either JSON or XML data, which instructs
user-agents how to interact with that data. I'd choose either JSON or
XML, instead of trying to do both, depending on whether you're more
> So if I use application/xml, my API would not be considered truly
No, not if you're using application/xml as the hypertext engine driving
application state. If it's just a snippet of XML which gets read by,
say, an HTML front-end driving application state, then it's OK because
the processing model (parse as XML, handling XInclude/XLink/rdf:about)
is adequate to the task. If that XML snippet contains URIs the user is
supposed to click on to transition the application to the next steady-
state (which aren't XLinks), well, that's what <a> and atom:link are
for, there's no corollary in application/xml (besides XLink).
Also, most order forms are simply tabular data, the semantics of which
don't exist in application/xml like they do in application/xhtml+xml or
text/html with <table>. Same with lists, same with forms.
> So now I'll ask, what media type I could possibly use with my own
> xml/json structure? It almost sounds like you're saying I shouldn't
> be returning my own made up structure, that I should instead use an
> existing media type, like one with xhtml or something. Is there a
> media type that allows for any sort of specific format to a domain to
> be returned? Or does that now fall into a case where I should create
> my own media type and register it with IANA?
It falls into a case where you should refactor. You have tabular data,
so you need to choose a data type which expresses such semantics (i.e.
HTML, or DocBook). The whole point of media types is that they are
_not_ domain-specific, but rather, represent a shared understanding of
a processing model at the network (IP) layer. This is the fundamental
tradeoff of the style:
"[A] uniform interface degrades efficiency, since information is
transferred in a standardized form rather than one which is specific to
an application's needs."
An order consists of item numbers, descriptions, quantity, unit price
and total price. You *could* re-invent the <table> wheel and register
it as a new media type, but it's more scalable (maintainable, portable)
to re-use HTML even if it isn't a precise fit. If you create a new
media type, then you need to distribute a custom user-agent. When you
upgrade your API, you must simultaneously update that user-agent.
The success of the Web is due to the common user-agent. What I really
don't want, is for any system I interact with to require me to install
yet another piece of software, and keep it up-to-date. That's coupling.
So much easier for everyone concerned, to target the browser. That way,
I only need to install and maintain one user-agent regardless of how
many different systems I interact with. Such decoupling allows clients
and servers to evolve independently. So there is a cost associated
with the minting of new media types -- coupling -- unless and until the
new media type achieves significant uptake.
On Sun, Dec 5, 2010 at 5:12 PM, Eric J. Bowman <eric@...> wrote:
> Anyway, it was previously discussed that the sentence in question is a
> bit buggy, which is in part to blame for the confusion. REST can be
> instantiated over IP by any protocol using media types, and meeting the
> other constraints like caching, not just by HTTP. But the media type
> is the means by which resource and representation are decoupled.
I see in table 5-1 "media type" is listed in the modern web
examples column. That does seem to bolster your argument. However,
the dissertation uses the term while describing the style rather than
http specifically. Your interpretation would seem to imply that a
stack (networking system and restful application protocol) that
eschewed iana registered media types would have to have to use a
different term for "the flavor of representations".
Perhaps it is a bug that the dissertation uses "media type" in the way
it does. However, that cannot be undone. Given that the dissertation
does use the term the way it does i stand by my assertion that there
are two valid uses of "media type". One which means a data format
that is registered with iana, and another that means a type, defined
by a specification, of representation used in a restful system.
Regardless, it seems a point of little importance.