RE: ATOM representation of search result facets

Hi Eric,

Thanks for your considered reply.  REST-Discuss is where I come to learn about REST from the best,
so this is a great place to have your understanding challenged and possibly learn something.

>> All that said, there is nothing about application/atom+xml which
>> implies this extension.
>>

> Nor does such requirement exist.


My understanding is that application/atom+xml describes atom *without* extensions.  If you put extensions in,
to *any media type*, via either new markup or even changing the meaning of standard atom markup, you should change media types,
because it is the media type which names / describes the preferred semantics of the message, and it is
the message metadata which is the most authoritative on the web:

http://www.w3.org/2001/tag/doc/mime-respect.html


> nothing in the self-descriptive messaging constraint which
> requires markup-language versioning to be expressed via media type

I don't see it as versioning, although I suppose you could think of it that way. I was thinking about
registered mime types as the standard.  If you extend a standard, you need to document it.  But, if you
extend it without changing the string that invokes the standard preferred semantics, how to disambiguate the
extended semantics?


> but it's incorrect to claim that using more application-
> specific media types makes the result more RESTful (or self-descriptive,
> or visible).

Mike A had a timely blog post related to this

http://www.amundsen.com/blog/archives/1136

In that post, he says this: This needs work as the word "standard" here is insufficiently defined.
What we're talking about here is related to what Mike was commenting on, the part of Roy's thesis where
it says " REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics "

So, given that not all semantics needed for a given interaction are described by a registered media type, we need to have
the ability to extend media types in order to describe semantics that are exchanged.

My personal understanding is that it is in this exact area where most "RESTful APIs" screw up: they exchange
messages using application/json, which says nothing besides "curly braces and arrays" (approximately) about their message.
Same for application/xml: "pointy brackets ahead" (again approximately).

FWIW, I'm not claiming to understand REST as a whole, and I rely on REST-Discuss to challenge my assertions, because otherwise,
people coming to REST-Discuss will receive bad information about what REST is or isn't.

So, my assertion is that, yes, it is necessary to engineer your media type to describe the message in order to be RESTful.  If you do not, you are not following a key constraint.   I see that as responding to bullet number 3 here:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Cheers,
Peter

________________________________
From: [email protected] [mailto:[email protected]] On Behalf Of Eric J. Bowman
Sent: September 1, 2012 02:52
To: Rushforth, Peter
Cc: Rich Cariens; [email protected]
Subject: Re: [rest-discuss] ATOM representation of search result facets



"Rushforth, Peter" wrote:
>
> All that said, there is nothing about application/atom+xml which
> implies this extension.
>

Nor does such requirement exist.

>
> To be self-descriptive, to pick up on the theme from another thread,
> the client has to request these semantics somehow, and the server has
> to communicate the fact that they are being provided. The RESTful
> way to do this is not through sniffing, but media types.
>

I see nothing in the self-descriptive messaging constraint which
requires markup-language versioning to be expressed via media type. To
me, REST is contained entirely within Dr. Fielding's dissertation,
including the definitions of terms used to distinguish one
architectural style from another. There are other ways of doing
things, but if they require any redefinition of Roy's terms in order to
be considered RESTful, the disservice isn't being done to REST(tm), but
to REST's usefulness as an evaluation tool.

Nobody has to implement REST, but if your idiom is that of networked
hypertext systems, an understanding of where you are deviating from
REST and the consequences of same, is required. We can't begin to
discuss the real-world consequences of overloading media type to
precisely capture the meaning of a hypertext interface, versus using
media type to identify a codec, unless we can agree that these are two
different approaches with different outcomes -- and thus worthy of
separate definitions so we can have that discussion using precise terms.

Which we can't do, if the starting point of the debate is that one of
these approaches just isn't RESTful enough, despite meeting Roy's
definition of self-descriptiveness, causing the discussion to degrade
into accusations of pedantry and un-usefulness. Do what's best for your
system, whether the result is precisely RESTful or not isn't a value
judgment, it's an evaluation tool. Instead of attempting to redefine
Fielding in an effort to attach the REST(tm) label, embrace REST the
tool by using Fielding's definitions to explain what tradeoffs you
made, and why you made them for the system in question.

REST is an idealized model, if fewer people would set it as a goal with
the naive expectation that real-world systems are even likely to fully
comply, we'd see less effort made to pass anything and everything off as
RESTful.

>
> If the client does request application/atom+xml and receives the
> extension, no harm is done because of atom's must ignore model.
>

Graceful degradation doesn't harm any clients, right.

>
> If the client does request the extension via a custom media type, it
> expects to be able to process the response based on the Content-Type
> value returned.
>

Now you're talking about no degradation, as if the only clients that
care about your payload are privy to your application. Having an
infinite number of finely-grained media types defeats the whole point
of self-descriptive messaging by actually reducing visibility, again
sticking with Roy's definition of terms. One key to the successful
scaling of the Web has been the small number of ubiquitous, coarse-
grained media types. This is a feature, not a bug; yes, there are
disadvantages, but it's a tradeoff we're willing to make in REST:

"The trade-off, though, is that a uniform interface degrades
efficiency, since information is transferred in a standardized form
rather than one which is specific to an application's needs."

Whether you are willing to make the same tradeoff in your system is for
you to decide, but it's incorrect to claim that using more application-
specific media types makes the result more RESTful (or self-descriptive,
or visible). What this tradeoff allows, is for your system to scale by
targeting the deployed architecture of intermediaries which do all
sorts of wonderful things with your content based on the ubiquitous
markup you're using, and simply don't care about understanding any of
your domain-specific vocabulary.

The reason fine-grained media types exclude intermediary participation,
is because you've tightly coupled client to server. As designed (by
which I mean coarse-grained), the concept of media types promotes loose
coupling. This has led to a proliferation of intermediaries performing
every task under the sun nowadays, for billions of *different* systems
using essentially *the same* small number of ubiquitous media types.
Restricting intermediaries to only those which fully understand every
last bit of domain-specific vocabulary your system uses, completely
misses the point of REST as an architectural style, by lacking the
key ingredient for meeting REST's scalability goal (ubiquitous media
types).

Profile attributes, otoh, offer a reasonable compromise by more fully
describing the document semantics (not to be confused with self-
descriptive messaging, currently the most prevalent misconception of
REST out there imo) while still identifying the coarse-grained codec
wire-speed clients (by which I mean intermediaries) need to determine
if there's *anything* they can do with the payload, which likely has
nothing to do with the specifics of your application.

-Eric