Subject: PaceServiceElement created

From: Antone Roundy <[email-masked]>
Date: Fri, 2 Jul 2004 09:31:18 -0600

I've posted PaceServiceElement on the wiki.  Since it's not scheduled 
for discussion yet, I'll just post the first little bit so that you'll 
know what it's about when it gets to the Proceed list.  (Note however 
that it is related to PaceIntrospection, which is currently under 
discussion).

Abstract

	This proposal defines a new element to be used in place of 
link[@rel="service.*"].

Related and Conflicting Proposals

     * PaceLinkPurpose
     * PaceLinkConstruct
     * PaceIntrospection

Rationale

	If PaceLinkPurpose is adopted, then link[@rel="service.post"] and 
link[@rel="service.edit"] will be clearly outside of the boundaries set 
for the link element (neither is an appropriate value for a clickable 
link), and thus will need a new element. Even if PaceLinkPurpose is not 
adopted, moving this logical group of @rel values to their own element 
would help to avoid excessive overloading of the link element.

Antone

---

From: Joe Gregorio <[email-masked]>
Date: Fri, 2 Jul 2004 12:41:59 -0400

> that it is related to PaceIntrospection, which is currently under

Interesting. Any reason for not creating an AtomAPI namespace?
For example:

<feed xmlnx:atomapi="http://purl.org/atom/api/ns#" ..

  <atomapi:post>http://...</atomapi:post>
  <atomapi:edit>http://...</atomapi:edit>

---

From: Joe Gregorio <[email-masked]>
Date: Sat, 17 Jul 2004 00:18:19 -0400

> would help to avoid excessive overloading of the link element.

I've looked at this again and instead of:

<atom:service name="edit" href="http://example.org/blah"/>

I would much prefer:

<atom:edit>http://example.org/blah</atom:/edit>

   -joe

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 17 Jul 2004 13:15:29 +0100

> <atom:edit>http://example.org/blah</atom:/edit>

My preference would be:

   <atom:edit rdf:resource="http://example.org/blah" />

but the chances of that happening are approaching zero :)

+1 to Joe in the meantime.

cheers
Bill

---

From: Eric Scheid <[email-masked]>
Date: Sat, 17 Jul 2004 22:17:32 +1000

> <atom:edit>http://example.org/blah</atom:/edit>

we don't want to put machine-readable data in element content instead of
attributes, do we?

so how about ...

    <atom:feed uri="..." />
    <atom:post uri="..." />
    <atom:edit uri="..." />
    <atom:delete uri="..." />

or would it be better to group them into a logical class, like this...

    <atom:service name='feed' uri="..." />
    <atom:service name='post' uri="..." />
    <atom:service name='edit' uri="..." />
    <atom:service name='delete' uri="..." />

?

e.

---

From: Dave Pawson <[email-masked]>
Date: Sat, 17 Jul 2004 13:39:10 +0100

>     <atom:service name='delete' uri="..." />

Much clearer semantics. 

I prefer the former, again for clarity of interpretation.
I also prefer the uri attribute agains href.
I really can't see any advantage in leveraging the href name;
its not been done for the majority of other atom elements, why pick on
this one?

Regards DaveP.
XSLT&Docbook  FAQ
http://www.dpawson.co.uk/xsl

---

From: Tim Bray <[email-masked]>
Date: Sat, 17 Jul 2004 07:36:37 -0700

> we don't want to put machine-readable data in element content instead 

Uh, why not? -Tim

---

From: Ken MacLeod <[email-masked]>
Date: 17 Jul 2004 09:43:55 -0500

Dave Pawson <[email-masked]> writes:

> I prefer the former, again for clarity of interpretation.  I also
> prefer the uri attribute agains href.  I really can't see any
> advantage in leveraging the href name; its not been done for the
> majority of other atom elements, why pick on this one?

The semantics are fuzzy on one point: what class of link is this?

The element name tells you the specific link relation name, but alone
doesn't tell you its link class.  Is it a human clickable link or an
Atom service link?

  <feed atom:id="tag:example.com,2004:main-feed"
        atom:location="http://example.com/main-feed.atom">
    <site atom:id="tag:example.com,2004:site"
          atom:location="http://example.com/site.atom">
      <title>Example Site</title>
      <alternate atom:clickable="http://example.com/"
                 type="text/html"/>
    </site>
    <entry atom:id="tag:example.com,2004:002"
           atom:location="http://example.com/002.atom">
      <author>
        <name>John Q Public</name>
        <link atom:clickable="generic:link"/>
        <ex:homepage atom:clickable="..."/>
        <ex:weblog atom:clickable="..."/>
        <feed atom:service="..."/>
      </author>
      <responds-to atom:uri="tag:example.com,2004:001"
                   atom:location="http://example.com/001.atom"/>
      <origin atom:ref="tag:example.com,2004:site"
              atom:location="http://example.com/site.atom"/>
      <alternate atom:clickable="http://example.com/002.html"
                 type="text/html"/>
      <edit atom:service="http://example.com/002.atom"/>
      <post atom:service="http://example.com/002.atom"/>

"Link classes" ("relation types" in LinkReferences) aren't an
"end-all" solution, as certain link classes are *not* suitable for
generic processing.  Some are however, like clickable links for
humans.

Link classes used here:

  atom:service -- Atom service endpoints
  atom:clickable -- user clickable links, clients recommended to
                    display all
  atom:id -- Atom resource identifier
  atom:ref -- Atom resource identifier reference that means "copy to
              downstream feeds" (synthetic feed info caching)
  atom:uri -- Atom resource identifier reference (non caching)
  atom:location -- Atom resource URI that contains a "last well known"
                   primary access mechanism for the resource, used
                   with atom:ref and atom:uri.

This is patterned after SkunkLink[1].  atom:clickable appears to have
the exact same meaning as SkunkLink's xml:href, if that's useful, but
I chose to only mention that here.

This is still thought-experiment territory.  There are issues with
links that the above addresses, but at the same time it makes them
more complex.  There are also other potential solutions, such as
clustering similar class links under one element, or providing an
"introspection" element to indicate specifically what links clients
should consider "clickable" (the primary class that can be used in a
generic fashion).

  -- Ken

[1] http://dubinko.info/writing/skunklink/

---

From: Sam Ruby <[email-masked]>
Date: Sat, 17 Jul 2004 10:47:38 -0400

>     <atom:service name='delete' uri="..." />

An <atom:feed> element directly inside of an <atom:feed> element doesn't 
feel right to me.  So, let's take a look at this in context. 
Immediately inside a feed, there is likely to be one or more of these 
elements, and immediately inside of an entry, there is likely to be a 
possibly different set.

Let's focus for a moment on an entry.  Likely to be contained within an 
entry are post, edit, and delete.  I will note that in many cases, the 
same uri is likely to be shared across these services.

This suggests an optimization:

   <atom:service name='post edit delete' uri="..." />

Two variations come to mind.  One is that the name post and delete 
correspond to the HTTP method, but that edit does not... this 
association could be strengthened by changing the name of the attribute, 
and in this one particular case, the value, thus:

   <atom:service method='post put delete' uri="..." />

Furthermore, it might even make sense to consider having a default for 
the method attribute - both to recognize and to encourage the common 
practice whereby multiple methods share a common endpoint.  This is 
without loss of generality or penalty for the general case where the 
endpoints are distinct: in such cases one simply inserts as many service 
elements as are required.

For simplicity, it may make sense to impose the rule that you may have 
exactly one service element with a default set of methods, OR you may 
have any number of service elements that each explicitly define a non 
overlapping set of methods.

  . . .

A similar set of considerations can be made for atom:service elements 
immediately inside of a feed, but let's take a look at the problematic 
case of a "feed" service, in the context of an actual feed:

   <atom:feed>
     <atom:service method="get" uri="..."/>
     <atom:entry/>
     <atom:entry/>
     <atom:entry/>
   </atom:feed>

The way this atom:service element is to be read is as follows: "while 
you may have retrieved this feed at a given URI, the service interface 
to GET a (possibly authenticated) feed intended to contain all the data 
needed for Atom protocol clients is at the following URI".

- Sam Ruby

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 17 Jul 2004 16:09:31 +0100

>     <atom:feed uri="..." />

As far as namespaces are concerned, this is the same name as 
/atom:feed, which may not be something you want/intend to happen.

cheers
Bill

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 17 Jul 2004 16:17:32 +0100

>   <atom:service name='post edit delete' uri="..." />

Is that meant to be an enumeration of the possible values for the 
name attribute, or a whitespace delimited list of methods in the 
name attribute?

>     <atom:service method="get" uri="..."/>

I don't see yet what the atom:service abstraction is offering direct 
element names.

Incidently, the act of eumerating the allowed methods/operations 
over a URI is what the link discussion should be focusing on.

cheers
Bill

---

From: Ken MacLeod <[email-masked]>
Date: 17 Jul 2004 10:39:14 -0500

Sam Ruby <[email-masked]> writes:

> An <atom:feed> element directly inside of an <atom:feed> element
> doesn't feel right to me.

D'oh!  I unintentionally did that in my example too.

Note that there are cases where the referencing element uses a
URI-reference to the referenced element, and both elements have the
same name.  This is used in ExtensibilityFramework and the <site> and
<author> synthesized feed examples I posted earlier.  In those cases
it's intentional, though.

  -- Ken

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 17 Jul 2004 16:45:27 +0100

>>>    <atom:service name='delete' uri="..." />

Seriously - what semantics?

> The semantics are fuzzy on one point: what class of link is this?

This is always going to be an issue with a generic element like 
atom:service whose meaning is to be determined by looking at one or 
more of its attribute values and not at the element name itself.

> doesn't tell you its link class.  Is it a human clickable link or an

I would argue that all the atom:service element tells you is that 
you need to look at its attributes.

If we keep going done this road we are going end up defining an 
ad-hoc type system for Atom's use of URIs. In my humble opinion 
that's a tarpit we want to stay well away from.

cheers
Bill

---

From: Antone Roundy <[email-masked]>
Date: Sat, 17 Jul 2004 10:01:31 -0600

On Saturday, July 17, 2004, at 08:47  AM, Sam Ruby wrote:
> I will note that in many cases, the same uri is likely to be shared 
> across these services.
>
> association could be strengthened by changing the name of the 
> attribute, and in this one particular case, the value, thus:
>
One question: assuming the API is going to provide a fallback method 
for servers that don't support PUT and DELETE, how does such a server 
expose it's endpoints?  (Of course, the same question will need to be 
answered however we specify the service elements, unless we were to 
drop PUT and DELETE completely.)  Perhaps the following:

    <atom:service name="delete" method="post" uri="..." />

Perhaps "method" could be "http-method" for clarity.  A server that 
DOES support DELETE could omit @method thusly:

    <atom:service name="delete" uri="..." />

In the case of the editing endpoint, 'name="put"' would be less clear 
than 'name="edit"', so the default method would not equal the endpoint 
name in that case.

I'm not sure I see any reason to require this:

    <atom:service name="get" uri="..." />
    <atom:service name="post" uri="..." />
    <atom:service name="delete" method="post" uri="..." />
    <atom:service name="edit" method="post" uri="..." />

as opposed to this:

    <atom:service name="get" uri="..." />
    <atom:service name="post delete edit" method="post" uri="..." />

One problem with all of this would be that people might think they 
could do this:

    <atom:service name="post delete edit" method="get" uri="..." />

I don't imagine we want to enable that.  So one more option might be 
something along the lines of:

    <atom:service name="post delete edit" rest="0" uri="..." />

with rest="1" being the default.

---

From: Tim Bray <[email-masked]>
Date: Sat, 17 Jul 2004 09:06:59 -0700

On Jul 17, 2004, at 8:45 AM, Bill de hÓra wrote:

> If we keep going done this road we are going end up defining an ad-hoc 
> type system for Atom's use of URIs. In my humble opinion that's a 
> tarpit we want to stay well away from.

+1

Furthermore, on the evidence we significantly lack expertise in 
building type systems.

-Tim

---

From: Dave Pawson <[email-masked]>
Date: Sat, 17 Jul 2004 19:00:34 +0100

> Seriously - what semantics?

Semantic markup Bill. 
I understand what a link is, I know what a uri is, I could even
guess what to put into a uri attribute.

> > The semantics are fuzzy on one point: what class of link is this?

See my other post. This thread so far hasn't addressed (that I saw)
any requirement | use case for classes.

> more of its attribute values and not at the element name itself.

I'd rather read the spec than guess what it means? Wouldn't you?

> that's a tarpit we want to stay well away from.

I'm guessing there are some motives behind all the issues?

-- 
Regards DaveP.
XSLT&Docbook  FAQ

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 17 Jul 2004 19:29:22 +0100

> guess what to put into a uri attribute.

I still don't get it.

> any requirement | use case for classes.

I didn't write that bit.

> I'm guessing there are some motives behind all the issues?

None I'm aware of.

cheers
Bill

---

From: Eric Scheid <[email-masked]>
Date: Sun, 18 Jul 2004 08:02:51 +1000

>   <atom:service name="delete" uri="..." />

Y'all realise that service.delete doesn't exist, right? I threw that in
there with the thought in the back of my head that an atom content server
could provide service.delete if it couldn't support http-method=DELETE, or
wanted to cater to atom-clients that were unable to send http-method=DELETE.
You'd probably use GET with some authentication on the URI.

    <entry>
        <id>/1233.atom</id>
        <atom:service name="delete" uri="/1233.atom?action=delete" />
        ...
    </entry>

e.

---

From: Ken MacLeod <[email-masked]>
Date: 18 Jul 2004 11:10:06 -0500

> Furthermore, on the evidence we significantly lack expertise in

I'm ok with ditching link type markup in the general case and relying
on the link name to be defined concretely in terms of both meaning and
usage pattern (class/type).

  <qname uri="URI"/>  or <qname>URI</qname>

Regarding the one link type that people seem most interested in being
both extensible and discoverable ("a link that is intended primarily
for presentation to a human user"[1]), maybe we can get some more
examples of extension link names where that discoverability would be
useful.  Mark Pilgrim's foray into b-link markup would be one example,
if those link names were in extensions and not the core.

Graham and Dare have indicated, if I read correctly, that they would
not implement such a feature in their aggregators, however.

  -- Ken

---

From: Ken MacLeod <[email-masked]>
Date: 18 Jul 2004 11:38:12 -0500

Sam Ruby <[email-masked]> writes:

> Let's focus for a moment on an entry.  Likely to be contained within
> an entry are [links for] post, edit, and delete.  I will note that
> in many cases, the same uri is likely to be shared across these
> services.
> 

Note here that 'edit' has a meaning whose implementation uses HTTP's
GET, PUT, and DELETE.  'edit' really means "this URI is actionable for
editing entries in the way an Atom implementation should expect", it's
not merely an alias for multiple HTTP methods.

>    <atom:service method='post put delete' uri="..." />

HTTP's POST method has a different meaning from Atom's 'post' service,
Atom's definition of 'post' is a lot more narrow than HTTP's.  It is
possible, for example, that new Atom service links will be defined
that may also use HTTP's POST but not be used for creating new
entries.

Conclusion: HTTP method names are not sufficient to derive "meaning"
or "usage" as a replacement of specific link names.

> over a URI is what the link discussion should be focusing on.

Agreed.  The allowed methods/operations over a URI are part of the
definition of the link name.

  -- Ken