Subject: PaceExtensionNamespace created

From: Antone Roundy <[email-masked]>
Date: Mon, 19 Jul 2004 20:33:28 -0600

http://www.intertwingly.net/wiki/pie/PaceExtensionNamespace

I may be crazy, but I've frittered away more time than it takes to 
listen to an episode of Car Talk creating another proposal to attack 
the whole Link conundrum.  It might be described as a fusion of 
PaceLinkPurpose, PaceServiceElement, PaceReplaceLinkElement, and who 
knows what else.  Here are the most interesting portions of the 
proposal:

Rationale

A number of extensibility issues have been raised, primarily in 
connection with the discussion of Link Constructs and the link element:

    1. The current extension model for the Link Construct, adding to the 
list of values for the link element's rel attribute, cannot not 
accomodate third-party extensions without introducing qnames in the rel 
attribute--an idea that has been strongly opposed by many.

    2. Some have recognized benefits to a third-party extensible Link 
Construct allowing default processing of unknown Link Constructs.

    3. The link element, as it now stands and as proposed by various 
proposals, is overloaded with a variety of different purposes: 
specifying hyperlinks (user-activatable links), pointing to API 
endpoints, pointed to content to be embedded, etc. Each of these 
classes of link could be grouped into a Construct which could benefit 
from extensibility.

Proposal

All changes are stated in relation to [WWW]this draft of the Atom 
Syndication Format

Insert the following before section 3.1:

3.1. Extension Namespace

The Atom Extension Namespace defines a number of attributes by which 
common constructs may be recognized. The extension namespace URI for 
this specification is:

       http://purl.org/atom/extension-ns#draft-ietf-atompub-format-01

The attributes defined by the extension namespace may be recognized in 
this specification by the namespace "atomex". Attributes from the 
extension namespace MUST be explicitly namespace qualified, meaning 
that the extension namespace MUST NOT be the default namespace. 
Elements, whether defined in this specification or by an extension, 
which use these attributes MUST conform the to requirements for that 
construct defined in the following sections. Additionally, such 
elements MUST NOT require understanding of any additional attributes or 
element children.

Replace section 3.4 with the following (section numbers below have NOT 
been adjusted to reflect the insertion or deletion of other sections):

3.4 Link Constructs

       A link construct specifies a hyperlink primarily intended to be 
activated through explicit user interactions such as clicking, 
selecting a menu item, drag and drop, etc. The resource pointed to MUST 
be accessible using only the indicated URI, wiht no additional XML or 
other content. When accessing the resource pointed to by the href 
attribute using HTTP, the GET method MUST be used.

It MUST NOT have any child content. A link construct has the following 
attributes:

Remove section 3.4.1 ("rel" Attribute)

Replace section 3.4.3 ("href" Attribute) with:

3.4.3 "atomex:link-href" Attribute

       The "atomex:link-href" attribute contains the link's URI. Link 
constructs MUST have an atomex:link-href attribute, whose value MUST be 
a URI [RFC2396].

       xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to 
the atomex:link-href attribute's content.

Insert the following after section 3.4:

3.5 Service Constructs

       A service construct specifies a link to an endpoint for the Atom 
API or an extension thereto. It MUST NOT have any child content. A 
service construct has the following attributes:

3.5.1 "atomex:service-href" Attribute

       The "atomex:service-href" attribute specifies the URI of an Atom 
API endpoint. Service constructs MUST have an atomex:service-href 
attribute, which MUST be a URI [RFC2396].

       xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to 
the atomex:service-href attribute's content.

3.5.2 "methods" Attribute

       The methods attribute specifies which HTTP methods can be used 
with the API endpoint. Service constucts MUST have a methods attribute. 
The value of this attribute is a space separated list of methods, which 
MUST only include methods supported for the API endpoint to which the 
service construct points, as specified by the controlling specification.

3.6 Embed Constructs

       An embed constrct specifies a link to external data intended to 
be automatically loaded asynchronously with and embedded in a feed or 
entry.

3.6.1 "atomex:embed-src" Attribute

       The "atomex:embed-src" attribute specifies the URI of the 
resource to be embedded. Embed constructs MUST have an 
"atomex:embed-src" attribute, which MUST be a URI [RFC2396].

       xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to 
the atomex:service-href attribute's content.

3.6.2 "type" Attribute

       The "type" attribute indicates an advisory media type; it MAY be 
used as a hint to determine the type of the representation which should 
be returned when the URI in the href attribute is dereferenced. Note 
that the type attribute does not override the actual media type 
returned with the representation.

       Embed constructs MAY have a type attribute, whose value MUST be a 
registered media type [RFC2045].

Replace section 4.2.2 with the following:

4.2.2 Link Construct Elements

       The following elements are link constructs.

4.2.2.1 "atom:alternate" Element

       The "atom:alternate" element specifies a link to an alternate 
representation of the feed. atom:head MUST contain at least one 
atom:alternate element. atom:head MUST NOT contain more than one 
atom:alternate element with the same type attribute value.

4.2.2.2 "atom:start" Element

       [[[Specification text be written]]]

4.2.2.3 "atom:prev" Element

       [[[Specification text be written]]]

4.2.2.4 "atom:next" Element

       [[[Specification text be written]]]

Insert section 4.2.3 as follows:

4.2.3 Service Construct Elements

       The following elements are service constructs.

4.2.3.1 "atom:edit" Element

       [[[Specification text be written]]]

4.2.3.2 "atom:post" Element

       [[[Specification text be written]]]

4.2.3.3 "atom:delete" Element

       [[[Specification text be written]]]

---

From: Ken MacLeod <[email-masked]>
Date: 19 Jul 2004 22:18:33 -0500

> http://www.intertwingly.net/wiki/pie/PaceExtensionNamespace

+1, iff we want link types.

> The attributes defined by the extension namespace may be recognized
> in this specification by the namespace "atomex".

The existing Atom namespace would work equally as well here:
atom:link-href, atom:service-href, etc.  But yes, the attributes must
still be explicitly namespace qualified.

>        The methods attribute specifies which HTTP methods can be
> used with the API endpoint. Service constucts MUST have a methods
> attribute. The value of this attribute is a space separated list of
> methods, which MUST only include methods supported for the API
> endpoint to which the service construct points, as specified by the
> controlling specification.

I don't see the purpose of this attribute.

Listing HTTP methods does not provide enough information to properly
use the endpoint, you still need to know what kind of resources can be
accessed there, what fields must be used/not used, etc.  All of that
information is already defined by the link relation name.

> 4.2.3.3 "atom:delete" Element

There is no delete endpoint.

  -- Ken

---

From: Antone Roundy <[email-masked]>
Date: Mon, 19 Jul 2004 21:43:34 -0600

> still be explicitly namespace qualified.
Yeah, it could be done either way.  To explicitly qualify it, if you 
want to use a default namespace for things that don't have to be 
explicitly qualified, you'd have to do this:

<feed xmlns="atom's namespace" xmlns:atom="atom's namespace">

...which works fine, but perhaps looks a little strange.

> information is already defined by the link relation name.
The purpose is for servers to indicate whether they support the 
preferred methods, which I assume are going to include GET POST PUT and 
DELETE, or only the fallback methods, which I assume will all run 
through GET and POST, or both.

> There is no delete endpoint.
I threw that in there on the assumption that the fallback method for 
servers that don't support DELETE might need it.

---

From: Ken MacLeod <[email-masked]>
Date: 19 Jul 2004 23:15:24 -0500

> > Listing HTTP methods does not provide enough information to
> > properly use the endpoint, you still need to know what kind of
> > resources can be accessed there, what fields must be used/not
> > used, etc.  All of that information is already defined by the link
> > relation name.

> preferred methods, which I assume are going to include GET POST PUT
> and DELETE, or only the fallback methods, which I assume will all
> run through GET and POST, or both.

If that were necessary, I'd suggest using a different attribute name
and value.  The attribute would be based on which types of support the
server offers, rather than HTTP method names.

However, I don't think *server* support is an issue with respect to
HTTP methods.  It's clients that have PUT/DELETE issues.  Servers will
implement all of the methods (e.g. always indicate they support all
methods), while clients really want to know if they can use the
fallback techniques if *they* need to.

Since server support of fallbacks are an all-or-nothing thing, there's
no need to include @method (or any other indicator) on every service
element, it'd be easier to put that in one place in the feed or site
introspection file.

  -- Ken

---

From: Walter Underwood <[email-masked]>
Date: Tue, 20 Jul 2004 12:01:01 -0700

> element, it'd be easier to put that in one place in the feed or site

There is some advantage to standalone documents. It sure would be
nice to have all the info right here, without needing to fetch one
more doc. In REST terms, I would like to fetch enough state to
make the next move.

I can see a use for @method in spiders as a safety mechanism.
Spider never want to do anything but a GET. Unless it is a spider
signing up a spammer for free catalog subscriptions, but that is
not our domain.

Hmmm, that makes me think. Should Atom require that non-GET URLs
return a 405 Method Not Supported on GET? That way, a spider can
decide to not return to that URL, even if they get there through
a normally-followed link.

wunder
--
Walter Underwood
Principal Architect, Verity

---

From: Ken MacLeod <[email-masked]>
Date: 20 Jul 2004 14:36:19 -0500

Walter Underwood <[email-masked]> writes:

> > Since server support of fallbacks are an all-or-nothing thing,
> > there's no need to include @method (or any other indicator) on
> > every service element, it'd be easier to put that in one place in
> > the feed or site introspection file.
> 
> more doc. In REST terms, I would like to fetch enough state to make
> the next move.

If we consider that necessary, I'd prefer the server report that
information in a header on every request, rather than on every service
URI reference in content.

  HTTP/1.1 200 OK
  Date: Tue, 20 Jul 2004 19:38:24 GMT
  Server: Apache/2.0.49-dev (Unix) DAV/2 SVN/1.0.5
  Last-Modified: Mon, 02 Sep 2002 07:58:11 GMT
  ETag: "94f4b-ffa-909c6ac0"
  Atom-Fallback-Support: Atom-Action; SOAP
  ...

> signing up a spammer for free catalog subscriptions, but that is

If spiders are randomly fetching anything that looks like a URI
location without understanding the Atom link relation names, I doubt
they're gonna be looking at the @method attribute either.

  -- Ken

---

From: Walter Underwood <[email-masked]>
Date: Tue, 20 Jul 2004 13:23:11 -0700

> they're gonna be looking at the @method attribute either.

The link names might be extensions. Yes, the spider should have
an exact list of the known @rel values. It is a safety method,
as I said.

wunder