RE: ATOM representation of search result facets

"Rushforth, Peter" <[email protected]> Fri, 14 Sep 2012 19:21:07 +0000
Newsgroups	gmane.comp.web.services.rest
Message-ID	<1CD55F04538DEA4F85F3ADF7745464AF1AE56487@S-BSC-MBX1.nrn.nrcan.gc.ca>
 Hey Mark,

Thanks for your reply.  

A few points inline.

Cheers,
Peter

> -----Original Message-----
> From: [email protected] [mailto:[email protected]] On Behalf Of 
> Mark Baker
> Sent: September 14, 2012 14:02
> To: Rushforth, Peter
> Cc: Eric J. Bowman; [email protected]
> Subject: Re: [rest-discuss] ATOM representation of search 
> result facets
> 
> Hey,
> 
> On Wed, Sep 5, 2012 at 12:03 PM, Rushforth, Peter 
> <[email protected]> wrote:
> > Hi Mark,
> >
> > Thanks for replying.
> >
> >> On Wed, Sep 5, 2012 at 8:09 AM, Rushforth, Peter 
> >> <[email protected]> wrote:
> >> > 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:
> >>
> >> That's not the case. It may well be the case for some - text/plain 
> >> comes to mind - but the majority of widely used media types are 
> >> designed well enough to accommodate non-breaking extensions (where 
> >> their introduction doesn't affect the meaning of the core content).
> >
> > IOW when served with that media type messages are 
> understood as that 
> > media type.
> 
> Right.
> 
> >  If a client/processor is looking for the extended 
> semantics how does 
> > it request them?
> 
> It doesn't, in general. If the extensions are standardized 
> and have value to the publisher (usually determined by the 
> quantity/quality of consumers), then the publisher will 
> probably just provide them for everybody since they're not 
> interested in dealing with the complexity of customizing 
> responses for the specific needs of each client (again, in general).

The key point here is _standardized_, and the scope of that standardization.
If my API documents
a parameter for a media type, it is standardized within my API and the scope of that
standard is my API.  Clients exchange and know about the media type
by building to my API.

How does a client developer rely on an extension which is not registered
with the mime type standardization tree.


> 
> >
> >>
> >> That said, there's some ambiguity here with regards to 
> when it makes 
> >> sense to use a different (or new) media type. An SVG 
> document wrapped 
> >> in "<html><body>" wouldn't be very useful served with the 
> text/html 
> >> media type, for example.
> >
> > ??: http://www.w3schools.com/html5/html5_svg.asp
> 
> Huh. Well, that example served me much better 10 years ago 
> before compound document features percolated to the 
> mainstream.

Well this is an example of an evolving media type I guess.  But it is
documented, and text/html is currently understood to include historically
svg content (or content that looks a lot like svg, anyway).

Browsers have evolved along with the media type.

> Though the point remains for the moment, as I 
> doubt all SVG clients are HTML5-enabled in this way,

Shouldn't that be the other way round?  html clients being svg enabled?
I too doubt any svg clients are html enabled in this way.

> meaning 
> that as an SVG publisher (and that sample document is, for 
> all intents and purposes, SVG) I should still be using image/svg+xml.

It is the html media type that is swallowing svg in this case.  I don't
know why they are doing this, but doubtless have some good reason.


> 
> >
> >> But an
> >> Atom document with a single entry extension from a foreign 
> namespace 
> >> is still an Atom document because the spec specifically 
> accommodates 
> >> such an extension; it should use application/atom+xml.
> >
> > I agree that it _can_ use application/atom+xml, but in 
> order to convey 
> > extended semantics, paging for example, it would need to use a 
> > different media type, application/atom+xml;type=feed in the paging 
> > case.
> 
> That's the same media type; application/atom+xml in both 
> cases. The use of a media-type-specific parameter doesn't 
> change the type. 

No its not the same type it is a new type but if you don't understand
the parameter you should ignore it.  I am not 
an authority on media types and it is a subtle art from what I see.

For example, the fallback behaviour RFC 3023 suggested for '+xml' 
which has become de facto practice in other registrations, had 
already been built into MIME via parameters.  And I've
never seen a processor which didn't understand a */something+xml type
fallback to the */xml semantics.  I'd like to see that, if someone
is aware of such.

> IIRC, James Snell wanted a separate media 
> type for Atom feeds vs. entries and I came up with the 
> compromise of the type parameter just so it could be safely 
> ignored in this way (or perhaps somebody came up with it and 
> I supported it, not sure).

OK, that's the history, thanks for that.  Good to know.  I would say
it worked out well, since the type parameter _can_ be used to
distinguish an atompub service, right?  IOW, if receive
a type parameter in the Content-Type, you know for sure the server
is at least aware of RFC 5023.

And if a client requests application/atom+xml;type=feed the server
(implementor) should realize that the client implementor is aware of
RFC 5023 and may be able to make good use of app:collection and
link@rel="next".




> 
> >
> >> In between those two extremes, the
> >> decision depends upon the specifics of the extensibility 
> features of 
> >> the
> >> type(s) in play, the importance and quantity of extended vs.
> >> core content.
> >
> > I don't think its a question of quantity, more of importance.  And 
> > importance is subjective.
> 
> Agreed, but IME, there's usually a correlation with quantity.




I don't know.  If you override the meaning of an attribute in atom,
can it still be safely processed as atom?  I know, you're going to 
say, depends on which attribute.  I'm not as strict in what I do 
as in what I tell others to do ;-).  Just trying to think it through!





> 
> >  If the extended semantics is important to a client, it will be 
> > requested, with Accept:.  If not, it won't. But if the extended 
> > semantics is just served with no signals for desire or of delivery, 
> > and clients actually do end up using the extended 
> semantics, that is 
> > out-of-band coupling of the nth degree IMHO.
> >
> >>
> >> Only the publisher knows what the content means, so they get to 
> >> decide which media type to use.
> >
> > I believe that it is the published definition of the media 
> type which 
> > is important, not the content.  A jpeg of my cat is not the same 
> > content as a jpeg of a supernova, but they both may have 
> the same media type definition.
> >
> > On the application tree,  application/json or 
> application/xml would be 
> > sufficient for almost everything.  But they aren't, so we 
> invent new 
> > media subtypes to describe the markup.  Atom is one, but I 
> don't think 
> > it stops there, not by a long shot.
> 
> Well, those two types aren't sufficient, but for different 
> reasons than what I think you're talking about (search the 
> archives for
> application/xml)
> 
> Media types are not a type system of arbitrary granularity 
> for your application, just a simple, very coarse-grained way 
> to associate some content with a specification for its 
> interpretation. You can of course define them as granular as 
> you like, but the less general they are, the less appealing 
> they are to support.

Again, I'm not sure. I think media type design can scale, from my API
to the Web.  Not everyone on the Web will want to support my API,
but that's ok, too.

Thanks for the good conversation!

Peter