|
|
Subject: Re: collections (was: Last whack at the issues) - msg#00133
List: network.syndication.atom.protocol
On 10/8/06 11:13 AM, "Duncan Cragg"
<duncan-j+cCvfF9c1rYtjvyW6yDsg@xxxxxxxxxxxxxxxx> wrote:
> Is there one 'collection' Atom Feed for APP use, and one normal
> Atom Feed for subscribers? In other words, is the collection
> URI also the Atom Feed URI? If not, it would be nice to say so
> and to say why not. I don't see any reason for two URIs but
> would like to see arguments for it if so.
In the simplest case: one collection, producing one subscription.
It is also entirely possible for multiple subscription feeds to be produced
from one collection, such as category subscriptions.
Further, it is entirely possible for there to be multiple collections which
end up being published as one subscription feed. Think collections of
entries, photos, reviews, caldav events ... all surfacing as one "my blog"
subscription feed.
And of course combine the two.. it's possible for multiple collections to
provide piecemeal input to multiple subscriptions.
Also note, and this is interesting, one might have an entries collection
managed by your blog provider, but the photos collection could be managed at
flickr ... and both being combined into a subscription feed. Thus two
completely different back end server systems for collections.
e.
Was this page helpful?
Thread at a glance:
Previous Message by Date:
click to view message preview
Re: Last whack at the issues
<co-chair-mode>
Here's how we'll do it. We'll buy into Sam's judgment on what should
be closed (so if you disagree, speak up). For the rest of them, we
will review the prior WG discussion of each Pace, so if you're happy
with where the WG got to, you need say no more.
:
It is our intent to close this discussion on August 16th, produce
another draft, do a formal Working Group Last Call (our Area Director
has requested this) and, following that, go to IETF last call.
</co-chair-mode>
I know it's a bit late and you're all looking to wrap this spec
up pretty soon, but I have some questions and observations to
make, which I have been saving up until I knew more about the way
you work and the history of APP. I'm both a relative newbie to APP
and a latecomer to the discussion, so I don't expect my comments
to be wholeheartedly embraced. :-)
Also, I'm sure much of what I say below has been argued to death in
the dense threads of the list, so I apologise in advance where this
is true. I tried tracking down discussion on a couple of my points,
but failed to navigate the thick undergrowth of APP history...
So, please perhaps treat my comments as advance warning of the
kinds of reactions you may expect to get once you finalise and
publish this protocol to a wider, non-list-contributing audience.
If you could see it this way, and not flame me, I would of course
be most grateful! :-)
I know everyone here wants to produce a protocol they're proud to
hold up as a great example of good engineering. I personally
want to be able to hold up the APP as a great example of how to do a
REST protocol. I don't want to have to qualify my enthusiasm...
So, here goes...
[All comments WRT draft 09]
Differentiating APP from 'Web' Service models
---------------------------------------------
When I first came across the APP, I was disappointed that it had
concepts such as introspection, discovery and service - all rather
non-REST, Servicey concepts - around the Introspection Document.
There is a danger of not differentiating the APP's REST
approach from the Service-Oriented world view that I and many
others are trying to distance ourselves from. In fact, we'd
like to use the Atom Publishing Protocol as an example of
how to do it better, without causing confusion by using
Servicey terms. The motivations of the list are perhaps not
the same as mine..!
Collections
-----------
Why invent new term 'member', for entry and 'collection' for
feed? Alternatively, if collection/member really is a different
thing from a feed - it really is a kind of elemental structural
data type - then why not use it for Introspection Documents: why
not just have collections of collections?
Here, a feed would just be a 'subclass', usage or specialisation
of the 'collection' type. This Introspection Document could be
a collection (site) of collections (workspaces) of collections
(feeds). Then one could have a few or as many nested collections
as one wished.
There are just too many concepts in the Introspection Document,
which jars against the preference towards simplicity we all like
as REST practitioners and protocol designers. It's also very
specific to the blog-site use-case. I know that's the whole
point - and what the WG is tasked with - but this restriction
is actually unnecessary even in that context.
Collections, Feeds and Entries
------------------------------
Is there one 'collection' Atom Feed for APP use, and one normal
Atom Feed for subscribers? In other words, is the collection
URI also the Atom Feed URI? If not, it would be nice to say so
and to say why not. I don't see any reason for two URIs but
would like to see arguments for it if so.
Atom Feed Document: is it optional whether this is just a list
of links to entries versus a normal Atom 1.0 feed with content
included alongside these links? Could we have an example of a
full Atom Feed Document/Collection, with URIs, if so?
The example URI for getting an entries Collection
'http://example.org/entries/go' is imperative in style (action
on the URL). It may be better to use the more declarative form
'http://example.org/entries/' (or
'http://example.org/entries/head' if you really want something
to indicate headness..).
Presumably the visibility of draft Entries is determined
by the auth on the Feed/Collection? Or is this the (single?)
case which justifies a separate Collection (editable) URI to
the Atom Feed (public, read-only) URI?
Why does the Introspection Document declare the 'accept'
mime type, not the collection itself? In REST, I understood
that the sense of what you could do comes from the thing
on which you intend act (e.g. a form inside a page), not
from a separate resource that points to it. Again, if the
nested collection approach were used, this would be where
'accept' would go - in the relevant collection itself (in
case there wasn't an enclosing collection to declare it).
Entry Editing: Separate URIs
----------------------------
Why do we need the word 'edit' in the URI? What is the point
of the <link rel='edit'..> and <link rel='edit-media'..>?
What's different about an Entry with 'edit' in it compared
to one without? What's the point of having a separate 'edit'
URI? 'Clients MUST NOT assume that the URI provided by the
Location header can be used to edit the created entry' - why
not? Isn't that the REST way? Shouldn't then the Location: URI
differ from this 'edit' URI, if you need it? What if you GET
the 'edit' URI? '.. SHOULD perform a GET on the member resource
before editing' - on which URI? the 'edit' one?
Thanks for listening - I hope what I'm asking makes sense, and
someone kind will reply in an informative, flame-free way!!
Cheers!
_____________________________________
Duncan Cragg
http://duncan-cragg.org/blog/
Next Message by Date:
click to view message preview
PaceOrderCollectionsByAppModified2
In reviewing the various paces regarding which way collections must be
sorted I found a hole:
----------------------------------------------------------------------------
* PaceAppModified describes using app:modified and also app:revision,
but no mention of how collections are sorted.
* PaceAppModified2 is simpler that PaceAppModified, defining
atom:modified. no mention of sorting.
* PaceConfigurableCollectionOrdering allows sorting by created, modified,
or updated dates, and a mechanism for explicitly exposing that sort
order in the collection. No mention of atom:published, invents
app:created (without naming it)
* PaceConfigurableCollectionOrdering2 is a simplified version of
PaceConfigurableCollectionOrdering, only exposing sorting by
atom:updated and app:modified
* RemoveMustOrderCollectionsByUpdated removes the explicit language of
sorting collections by atom:updated, and implies sort order will remain
undefined.
* PaceOrderCollectionsByAppModified wasn't on Sam's list (this was closed
before the recent in-depth discussions), describes collections being
sorted by pub:modified (text needs updating for 09 nouns, but concept is
compatible with 09)
----------------------------------------------------------------------------
So ... the options we have available are (1) make sort order undefined, (2)
make sort order variable, (3) leave sort order broken (ie. atom:updated) ...
which leaves out option (4) define one, useful, sort order.
Thus, and in consideration of the *extensive* recent discussions, I've
updated Thomos Broyer's PaceOrderCollectionsByAppModified to be protocol-09
compatible, and also trimmed it to be just the sorting spec text.
In section 9, replace the second paragraph with:
The entries in the returned Feed MUST be ordered by their
'xxx:modified' property (Section 8.xx), with the most recently
modified entries coming first in the document order.
Assumes PaceAppModified2 gets up.
e.
Previous Message by Thread:
click to view message preview
Re: Last whack at the issues
<co-chair-mode>
Here's how we'll do it. We'll buy into Sam's judgment on what should
be closed (so if you disagree, speak up). For the rest of them, we
will review the prior WG discussion of each Pace, so if you're happy
with where the WG got to, you need say no more.
:
It is our intent to close this discussion on August 16th, produce
another draft, do a formal Working Group Last Call (our Area Director
has requested this) and, following that, go to IETF last call.
</co-chair-mode>
I know it's a bit late and you're all looking to wrap this spec
up pretty soon, but I have some questions and observations to
make, which I have been saving up until I knew more about the way
you work and the history of APP. I'm both a relative newbie to APP
and a latecomer to the discussion, so I don't expect my comments
to be wholeheartedly embraced. :-)
Also, I'm sure much of what I say below has been argued to death in
the dense threads of the list, so I apologise in advance where this
is true. I tried tracking down discussion on a couple of my points,
but failed to navigate the thick undergrowth of APP history...
So, please perhaps treat my comments as advance warning of the
kinds of reactions you may expect to get once you finalise and
publish this protocol to a wider, non-list-contributing audience.
If you could see it this way, and not flame me, I would of course
be most grateful! :-)
I know everyone here wants to produce a protocol they're proud to
hold up as a great example of good engineering. I personally
want to be able to hold up the APP as a great example of how to do a
REST protocol. I don't want to have to qualify my enthusiasm...
So, here goes...
[All comments WRT draft 09]
Differentiating APP from 'Web' Service models
---------------------------------------------
When I first came across the APP, I was disappointed that it had
concepts such as introspection, discovery and service - all rather
non-REST, Servicey concepts - around the Introspection Document.
There is a danger of not differentiating the APP's REST
approach from the Service-Oriented world view that I and many
others are trying to distance ourselves from. In fact, we'd
like to use the Atom Publishing Protocol as an example of
how to do it better, without causing confusion by using
Servicey terms. The motivations of the list are perhaps not
the same as mine..!
Collections
-----------
Why invent new term 'member', for entry and 'collection' for
feed? Alternatively, if collection/member really is a different
thing from a feed - it really is a kind of elemental structural
data type - then why not use it for Introspection Documents: why
not just have collections of collections?
Here, a feed would just be a 'subclass', usage or specialisation
of the 'collection' type. This Introspection Document could be
a collection (site) of collections (workspaces) of collections
(feeds). Then one could have a few or as many nested collections
as one wished.
There are just too many concepts in the Introspection Document,
which jars against the preference towards simplicity we all like
as REST practitioners and protocol designers. It's also very
specific to the blog-site use-case. I know that's the whole
point - and what the WG is tasked with - but this restriction
is actually unnecessary even in that context.
Collections, Feeds and Entries
------------------------------
Is there one 'collection' Atom Feed for APP use, and one normal
Atom Feed for subscribers? In other words, is the collection
URI also the Atom Feed URI? If not, it would be nice to say so
and to say why not. I don't see any reason for two URIs but
would like to see arguments for it if so.
Atom Feed Document: is it optional whether this is just a list
of links to entries versus a normal Atom 1.0 feed with content
included alongside these links? Could we have an example of a
full Atom Feed Document/Collection, with URIs, if so?
The example URI for getting an entries Collection
'http://example.org/entries/go' is imperative in style (action
on the URL). It may be better to use the more declarative form
'http://example.org/entries/' (or
'http://example.org/entries/head' if you really want something
to indicate headness..).
Presumably the visibility of draft Entries is determined
by the auth on the Feed/Collection? Or is this the (single?)
case which justifies a separate Collection (editable) URI to
the Atom Feed (public, read-only) URI?
Why does the Introspection Document declare the 'accept'
mime type, not the collection itself? In REST, I understood
that the sense of what you could do comes from the thing
on which you intend act (e.g. a form inside a page), not
from a separate resource that points to it. Again, if the
nested collection approach were used, this would be where
'accept' would go - in the relevant collection itself (in
case there wasn't an enclosing collection to declare it).
Entry Editing: Separate URIs
----------------------------
Why do we need the word 'edit' in the URI? What is the point
of the <link rel='edit'..> and <link rel='edit-media'..>?
What's different about an Entry with 'edit' in it compared
to one without? What's the point of having a separate 'edit'
URI? 'Clients MUST NOT assume that the URI provided by the
Location header can be used to edit the created entry' - why
not? Isn't that the REST way? Shouldn't then the Location: URI
differ from this 'edit' URI, if you need it? What if you GET
the 'edit' URI? '.. SHOULD perform a GET on the member resource
before editing' - on which URI? the 'edit' one?
Thanks for listening - I hope what I'm asking makes sense, and
someone kind will reply in an informative, flame-free way!!
Cheers!
_____________________________________
Duncan Cragg
http://duncan-cragg.org/blog/
Next Message by Thread:
click to view message preview
Re: collections
Is there one 'collection' Atom Feed for APP use, and one normal
Atom Feed for subscribers? In other words, is the collection
URI also the Atom Feed URI? If not, it would be nice to say so
and to say why not. I don't see any reason for two URIs but
would like to see arguments for it if so.
In the simplest case: one collection, producing one subscription.
It is also entirely possible for multiple subscription feeds to be produced
from one collection, such as category subscriptions.
Further, it is entirely possible for there to be multiple collections which
end up being published as one subscription feed. Think collections of
entries, photos, reviews, caldav events ... all surfacing as one "my blog"
subscription feed.
And of course combine the two.. it's possible for multiple collections to
provide piecemeal input to multiple subscriptions.
Also note, and this is interesting, one might have an entries collection
managed by your blog provider, but the photos collection could be managed at
flickr ... and both being combined into a subscription feed. Thus two
completely different back end server systems for collections.
e.
Thanks very much for this excellent reply. :-)
So excellent, in fact, that I think the text should appear in some form
in the spec! Surely this kind of thing would be helpful to future
implementors? It's completely cleared up this issue for me, and I'm
sure others will be asking similar questions.
If I could extend and summarise your points a bit:
"A Collection takes the form of an Atom Feed (modulo paging and
draftness - and if there's others, it would be good to list them here),
but is oriented towards editor clients, not subscriber clients. There
may or may not be a one-to-one relationship between APP Collections and
public Atom Feeds. Collections are generally secured where Atom Feeds
are generally public".
Surely making these points explicit will help readers? (Have I
paraphrased correctly?)
Now, do Collections normally just contain URIs of Entries, or the full
content? I believe it is redundant to return the full, or even
partial/summary, content, but the spec hints that content of some sort
may appear: clients 'SHOULD perform a GET on the member resource before
editing' (sec 9.).
Indeed, can I boldly suggest that the spec explicitly says the
collection feed 'SHOULD NOT' have any content - because such content has
not got a specific purpose in the APP world? A blog publishing client
can fetch each entry it hasn't cached and save network bytes in the
process (perhaps setting a standard for feed readers to follow!). As I
mentioned in my email, an example in the spec of what a typical
Collection feed might look like will help enormously.
Which leads me on to another point I was hoping to clear up in my mind:
on what URI does the client 'perform a GET before editing'? Is the
'edit' URI/link-rel synonymous with 'member' of a collection which is
synonymous with 'full editable form' which is synonymous with 'provided
in the Location header on create'?
In sec 8.1, it states 'Clients MUST NOT assume that the URI provided by
the Location header can be used to edit the created entry'. Yet the
examples consistently show the Location: URI being the one with 'edit'
in it, that is then also duplicated in the link-rel-edit URI. When
might they differ? Indeed, when are any of the above-listed synonyms
broken? If there are any, they should probably be explicitly documented
so people like me don't get confused.. :-)
Another minor issue I asked about before is the use of 'edit' in the
URI: if this is the XML/Atom form of an HTML Entry page, surely it
should have a URL like:
http://myblog.com/postings/what_my_cat_did_today.atom
for the Atom equivalent of the HTML page:
http://myblog.com/postings/what_my_cat_did_today.html ?
If there's some concept I've missed that means this is wrong, please
explain, otherwise please confirm that the use of 'edit' mid-URI is
arbitrary and even perhaps .. misleading or inappropriate?
Finally (sorry to use up attention credits!), why is there link-rel-edit
at all once we're in APP-land? I can understand having this to point
from HTML to XML (as originally conceived by Joe Gregorio in
'Deconstructing the AtomAPI', back in 2003 - yes, I have been doing some
APP archaeology!), from public Atom feed to APP member/entry, and from
APP Collection to its members, but why duplicate these links in the XML
of the entry itself? Indeed, Collection->Member/Entry should perhaps be
link-rel-member?!
Once again, thanks for your clear and non-hostile response! :-) I am
actually happy that asking questions like this can help firm up the spec
and make its life much longer - as long as I get answers, some of which
are followed by clarifications in the text....
Duncan
_________________________________
Duncan Cragg
http://duncan-cragg.org/blog/
|
|