RE: ATOM representation of search result facets

Hi Erik,

Thanks for this feedback.

> RFC 5005 is the atom feed paging RFC, if I'm not mistaken, and it was standardised _before_ AtomPub, RFC 5023.
> So this requirement that the capability of paging be implied by clients requesting ;type=feed doesn't make any sense.

RFC 5005 does not address the atom media type, it is a link relation registration.  So it does not extend the
semantics of application/atom+xml, from my POV.  See below.

RFC 4287, section 2 states that entries and feeds are covered by the one media type.  But it pre-dates
RFC 5023 which I agree provides wiggle room around the type parameter.   Including the recommended
sniffing of the root element if the type parameter is not present, which might be considered a bad practice.
Indeed, if you went by only RFC 4287, you would be obliged to sniff the root element to determine how
to process the response.  I guess the fact that collections and members are sometimes distinct by their
context must have lead the collaborators on 4287 to conclude that further disambiguation was not necessary.

> When you implement a component that speaks in terms of a standardized media type, with known,
> standardized extensions, then there's no need for clients to signal their support for this or that extension.

Where the media type registration is updated by the extension, I agree. Otherwise, any extension anywhere could be
considered as part of that media type.  Even the overloading of link@length<mailto:link@length> via an email to REST-Discuss.

For example, the IANA registry lists both atom RFCs under the one registration, and the type parameter was specifically added
by the higher number RFC.  Therefore, clients that request and servers that serve that parameter can (should imho) be
reliably expected to understand and support the semantics of the later RFC.  The type parameter wiggle room is provided by the
later RFC in an effort to be backwards compatible, I think.  Backwards compatibility is a requirement of the
media type registration process, I believe.

> If, indeed each extension of Atom/AtomPub needed its own media type, why don't any extensions define new media types?
> Had they done so, a proliferation of media types would ensue

That is a good question.  I think additional parameter+values, such as 'profile=foo' could be useful in that regard.  Media type proliferation
would not be a problem if that was the mechanism used.  Processors which don't recognize a parameter are required to
ignore it.  So the original parent media type would not be obscured, which is a goal.  In fact, if your API uses some
custom extension which is specific to your API, why not signal /scope it by adding a custom parameter+value to the base
media type (profile=myapi)?  It is standard in the sense that the parent (standard) media type is not obscured.

> 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.

I disagree, based on the fact that Atom defines an open registry for link
relations, it adopts a "must-ignore" policy for elements that the agent "does not understand",
not for elements "not defined in this spec"

I don't understand the distinction you are making.  I think you're trying to say that any extension, defined anywhere, can be
an extension that a processor can follow.  Where is the standards in that?   If you don't think that's coupling,
we'll have to agree to disagree.  A better way IMHO would be to define and use a custom media type parameter as discussed
above.

Cheers,
Peter

________________________________
From: [email protected] [mailto:[email protected]] On Behalf Of Erik Mogensen
Sent: September 5, 2012 14:58
To: Rushforth, Peter
Cc: Mark Baker; [email protected]; Eric J. Bowman
Subject: RE: [rest-discuss] ATOM representation of search result facets


Den 5. sep. 2012 18:03 skrev "Rushforth, Peter" <[email protected]<mailto:[email protected]>> følgende:
>
[....]

> > 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.
>
You keep referring to the feed paging case, but it doesn't make any sense to me.

RFC 5005 is the atom feed paging RFC, if I'm not mistaken, and it was standardised _before_ AtomPub, RFC 5023. So this requirement that the capability of paging be implied by clients requesting ;type=feed doesn't make any sense.

A resource is rarely both a feed and an entry, and the introduction of the type format was AFAICT done to make it easier to differentiate between the two, NOT to imply conformance with AtomPub. Indeed, RFC 5023 states that:

"Producers of Atom Entry Documents SHOULD use the "type" parameter regardless of whether or not it is mandatory. Producers of Atom Feed Documents MAY use the parameter." [5023-12.1.1]

When you implement a component that speaks in terms of a standardized media type, with known, standardized extensions, then there's no need for clients to signal their support for this or that extension.

If, indeed each extension of Atom/AtomPub needed its own media type, why don't any extensions define new media types?  Had they done so, a proliferation of media types would ensue, and IMHO /that/  wouldn't be in the spirit of the architcture of the web...

No server admin in their right mind would conneg between different dialects of atompub, the way they did user-agent based HTML back in the last decade...  Either an Atom feed has the extensions, or it doesn't. For a feed with no next link, it's either there or not.

RFC 5005 even describes a new subtype of atom feeds, namely archived feeds, with details on detection and semantics. All with the same media type.

> 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.

I disagree, based on the fact that Atom defines an open registry for link relations, it adopts a "must-ignore" policy for elements that the agent "does not understand", not for elements "not defined in this spec"

(earlier:)

> If a client/processor is looking for the extended semantics
> how does it request them?

It hopes that they're there. If not, it tries its best to complete its task.  Just as you would if you were faced with a site that didn't use CSS, and looked ugly, even though you happen to run a browser that /does/ support CSS.

(I can hear the hipsters go "there was a time before CSS?")

[5005] http://tools.ietf.org/html/rfc5005
[5023] http://tools.ietf.org/html/rfc5023
[5023-12.1.1] http://tools.ietf.org/html/rfc5023#section-12.1.1

TTFN!
--
-mogsie-