Subject: Re: collections (was: Last whack at the issues) - msg#00133

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/