Hi Alistair, Thanks for this detailed analysis. I believe your point is completely valid, and I hadn't considered it before. Some thoughts in line ...
> Apologies again, please bear in mind these comments are based on a partial > reading of the doc, will hopefully have more time to read in full soon. More > inline... > > On Mon, Mar 14, 2011 at 06:08:56PM +0000, Richard Jones wrote: >>> I notice in the current spec you overload the 'edit-media' relation to >>> define new protocol behaviour when POSTing binary content to a deposit's >>> edit-media URI. >> >> I'm not sure what you mean, sorry. We haven't specified any >> behaviour for POST on the edit-media URI (EM-URI in the document). >> We do a PUT on that URI which I think is consistent with the AtomPub >> approach (replace the old file with the new file). We do do a POST >> on the edit URI (Edit-URI in the document) which isn't covered by >> AtomPub at all, but is consistent with a RESTful approach. Is it >> that that bothers you? > > Sorry, I must've mis-read first time. Now I'm reading section 6.6.1 "Adding > New Packages or Files to a Container"... > > ...OK, yes I think I would object to using the edit-URI for this purpose. > Well, > actually, no, I don't care what URI you use, what I would object to is > specifying the use of the 'edit' link relation to indicate which URI can be > used for this purpose. > > I'm just trying to come at this from a REST/hypermedia point of view. > > What this spec effectively does is to change the meaning of the 'edit' > link relation, or in this case to "overload" it by giving it an additional > meaning over what IANA (via the AtomPub spec) has to say about it. > >> From a practical point of view, as a client developer, how do I know when > the 'edit' link means only what it says in the IANA registry, and when the > 'edit' link also means what it says in the SWORD spec? Yup, this is a key insight. We are in want of polymorphism in @rel values ... > E.g., say my client receives an Atom entry document. The client finds an > 'edit' link, and because it's programmed with knowledge of atompub, it then > knows what URI to use to update or delete the entry. But how does my client > additionally know that the URI at the end of the 'edit' link also supports > adding new packages or files to a container? Should it look for other sword: > foreign markup in the entry document, then modify its understanding of the > 'edit' link relation based on the presence of this markup? Or should it just > assume that the 'edit' link means this in all cases, and just attempt the > operation (which may fail if it was actually just talking to a plain old > atompub server)? For simplicity in the profile this is what I would expect. As it is in the profile SWORDv2 allows for any URI to respond with Method Not Allowed or Not Implemented. But from a client implementation point of view, is this too indistinct? We could ensure that the server always announces to the client that it is a sword server, by mandating the use of a sword:version element in the atom:entry (deposit receipt). This is already mandated in the app:service element, so it would be a minimal extension. > Instead of specifying what operations the Edit-URI should support, which is > effectively redefining/overloading the meaning of the 'edit' link relation, > I would suggest that the SWORD specification simply define a new link > relation, e.g.: > > http://purl.org/net/sword/rel/append-package-contents > > Client developers would then know to use this link relation when looking for > the URI to use to POST additional package contents too. And server developers > would be free to implement this behaviour using whatever URIs they choose - > they could do it with the edit-URI, or they could do it with a completely > different URI, it's up to them, and it doesn't matter for the client because > the client is hypermedia-driven. So this would be an explicit way of just asserting that the URI can be used for that purpose, but in the profile we could say that the Package Contents URI MAY be the same as the Edit-URI. That's sort of a question, and sort of just me reflecting back what you're saying to confirm that I've understood. If I have understood, I like the approach - we wouldn't need to include the sword:version in the atom:entry as I suggest above in this case. > To labour this point a bit more, by specifying that the edit-URI has to > be used for this purpose, you are placing unnecessary constraints on how > servers are implemented. I.e., as a server implementer, I'm now forced to > extend/override/modify my existing server-side code for handling requests to > edit-URIs to implement this behaviour. If instead you just define a new link > relation, then server developers are free to stick this new behaviour at any > URI of their choosing, which gives the server-developer far more freedom in > how > the behaviour is implemented. And it's also simple and crystal-clear for > client > developers how a client decides which URIs to use for what protocol behaviour. Ok, great, that seems pretty convincing to me. > Similarly for any other new protocol operations you want to specify, I would > suggest defining new link relations, rather than specifying what URIs should > be used or changing the meaning of any existing link relations like 'edit' > or 'edit-media'. > > So, e.g., for "Adding New Metadata to a Resource", rather than specifying that > the edit-URI should be used, the spec could define a new link relation like: > > http://purl.org/net/sword/rel/append-metadata > > Similarly for "Adding New Metadata and Packages or Files to a Resource > with Multipart". > > Am I making sense? Yes, completely. I'd like to solicit a bit of feedback from others on how they feel about extending the number of @rel elements we use. I'd like to keep all extensions to a minimum above AtomPub, so the fewer we use the better. Folks? In the mean time, can you, Alistair, offer me your analysis on which other protocol operations should have their own @rel values? Beyond the ones above, that is. Cheers, Richard > [1] > http://swordapp.org/wp-content/uploads/2011/03/SWORDProfile.html#protocoloperations_addingcontent_binary > > >> >>> I wonder if an alternative pattern might give you a bit more flexibility, >>> and be a bit easier to implement, without having to define any new protocol >>> behaviour. >>> >>> Let's assume you've done a GET on the service document URI and chosen a >>> collection URI to work with already. >>> >>> As described in the spec, you then create a new deposit by POSTing some >>> packaged binary content to the collection URI. In return you get a 201 with >>> an Atom entry document. >>> >>> The returned Atom entry document has an "edit" link and an "edit-media" link >>> as usual, and also a new link - let's call it "package-contents" for now, >>> what it's called doesn't really matter for this email, it's the pattern I'd >>> like to focus on. E.g.: >>> >>> <entry xmlns="http://www.w3.org/2005/Atom";> >>> <title>al's first deposit</title> >>> ... >>> <link rel="edit" type="application/atom+xml;type=entry" >>> href="http://example.org/deposit/foo.atom"/> >>> <link rel="edit-media" type="application/zip" >>> href="http://example.org/deposit/foo.media"/> >>> <link rel="package-contents" type="application/atom+xml;type=feed" >>> href="http://example.org/unpacked/foo"/> >>> ... >>> </entry> >>> >>> If you want to update (replace) the entire packaged content for this >>> deposit, >>> you would do a PUT on the edit-media URI as per standard Atom protocol. >>> >>> If you want to update (replace) the metadata for this deposit, you would do >>> a PUT on the edia URI, again as per standard Atom protocol. >>> >>> Now, what's implicit here is that, as a side-effect of the initial POST >>> request to create the deposit, the server will have unpacked the packaged >>> content, and is now exposing the unpacked media resources as a standard Atom >>> collection, which is discoverable via the "package-contents" link. >>> >>> I.e., if you were to do a GET on the package-contents link URI, the server >>> would return an Atom feed listing all of the media resources within the >>> package. E.g.: >>> >>> <feed xmlns="http://www.w3.org/2005/Atom";> >>> ... >>> <link rel="self" type="application/atom+xml;type=entry" >>> href="http://example.org/unpacked/foo"/> >>> <link rel="deposit" type="application/atom+xml;type=entry" >>> href="http://example.org/deposit/foo.atom"/> >>> ... >>> <app:collection href="http://example.org/unpacked/foo";> >>> <title type="text">package contents for al's first deposit</title> >>> <app:accept>*/*</app:accept> >>> </app:collection> >>> ... >>> <entry> >>> ... >>> <link rel="edit" type="application/atom+xml;type=entry" >>> href="http://example.org/unpacked/foo/resource1.atom"/> >>> <link rel="edit-media" type="text/plain" >>> href="http://example.org/unpacked/foo/resource1.media"/> >>> ... >>> </entry> >>> <entry> >>> ... >>> <link rel="edit" type="application/atom+xml;type=entry" >>> href="http://example.org/unpacked/foo/resource2.atom"/> >>> <link rel="edit-media" type="image/jpeg" >>> href="http://example.org/unpacked/foo/resource2.media"/> >>> ... >>> </entry> >>> ... >>> </feed> >>> >>> If the server supported adding further media resource to the package, you >>> could advertise this by including an app:collection element within the feed >>> document, as per [2]. I.e., clients would do a POST to the package-contents >>> collection URI, as per standard Atom protocol for creating media resources >>> in a collection. >> >> This sounds very similar to what could be achieved with the >> sword:statement. The statement URI appears in the atom:entry and >> allows you to content negotiate for either an OAI-ORE or Atom Feed >> document describing the contents of the resource. Further to that, >> in order to satisfy the desire to be consistent with GData, we have >> added a condition that allows the Edit-URI to be content negotiated >> for as an atom:feed rather than an atom:entry which would then list >> the collections and entries in that object. Would that meet your >> requirements as discussed here? >> >> We have explicitly avoided saying anything about GData semantics in >> the spec, but we do want to ensure that we don't impede any attempt >> to implement it alongside SWORD. >> >> I'd be interested in your opinion on the Atom Feed serialisation of >> the Statement as described at: >> >> http://swordapp.org/wp-content/uploads/2011/03/SWORDProfile.html#statement_atom >> >> and any enhancements to that serialisation (which I threw together >> very quickly) which we could do along the lines of what you suggest >> above would be gratefully received. >> >>> If you wanted to delete any media resources within the package, then each >>> media resource would have it's own URI which you could send a DELETE to. If >>> you wanted to delete the whole package, you could still do a delete on the >>> deposit's edit-media URI as specified in the current SWORD protocol spec. >>> >>> I just wonder if this pattern would give you more flexibility over managing >>> the contents of a deposited package, whilst at the same time requiring less >>> specification of non-standard Atom protocol behaviour. I.e., this pattern >>> needs no new protocol behaviour to be specified, all it needs is that you >>> define the "package-contents" link relation (or whatever you want to call >>> it) >>> as pointing to an Atom collection containing the unpacked deposit contents. >>> >>> It also might be easier to implement, because rather than servers having >>> to extend their Atom protocol engine with new operations, now everything is >>> standard Atom protocol, and all servers need to do is implement a >>> side-effect >>> of the initial deposit request to unpack the package and store it in a >>> new collection. >> >> I think that this is where we'd like to be in the long run, but this >> version of SWORD is limiting itself to just extending to the most >> primitive CRUD implementation, just so that we can get that to work. >> I would absolutely encourage real world implementations to go this >> route. >> >>> On a different point, I also notice in the current spec that you overload >>> the 'edit' link relation to define new protocol behaviour when POSTing an >>> Atom entry document to the edit URI. I'm guessing that what you want here >>> is partial update? I'm just wondering how easy this would be to implement, >>> I'm just thinking that it may not be obvious how any child elements should >>> be handled, whether they should add or replace existing elements. Telling >>> the >>> difference may require the server to have knowledge of element >>> cardinalities, >>> which would be hard to guarantee in general where clients may use extension >>> elements. I was just thinking if what you want to do is selectively update >>> portions of the deposit's metadata record, then you might be better of using >>> PATCH instead of POST, and then having a discussion around the media-type >>> recommended for PATCH requests, and how they should be processed. Some of >>> the issues with dealing with this type of request are discussed at [3]. >> >> We're also explicitly avoiding talking about metadata and how it is >> managed in detail, although PATCH may be the way in the long run >> (that's how WebDAV does it, right?). >> >> I am interested to see how difficult it is for the client and server >> implementations funded by the project to implement this >> functionality, and we will modify the spec if it turns out to be a >> significant burden. The use case that I have in mind is that I >> upload a single binary file (say a PDF of my research paper) and >> then later on I want to upload another file to the item (perhaps the >> XLS of my supporting data). The way to do that with REST is to just >> POST the resource to where I want it to be created, so this is the >> approach we went for with SWORD. >> >> It's also important for us to communicate that we are not imposing >> specific behaviours on a server with regard to how content is >> managed (that's the domain of CMIS as far as I can tell), so if a >> server can't manage to unpack a file and add the content and >> metadata in a way which makes sense, then it is free to reject, >> partially complete or whatever else it thinks appropriate. Does >> that make sense? >> >>> Anyway, hope this helps, and please feel free to criticise these ideas. I'm >>> in the process of reviewing the design for a new data repository, and would >>> like to be close to SWORD if possible. >> >> This is very helpful, thanks for such a detailed analysis. >> >> Cheers, >> >> Richard >> >> >>> >>> Cheers, >>> >>> Alistair >>> >>> [1] >>> https://sword-app.svn.sourceforge.net/svnroot/sword-app/spec/trunk/SWORDProfile.txt >>> [2] http://tools.ietf.org/html/draft-divilly-atompub-discovery-00 >>> [3] http://code.google.com/apis/gdata/docs/2.0/reference.html#PartialUpdate >>> >>> On Mon, Feb 14, 2011 at 07:10:12PM +0000, Richard Jones wrote: >>>> Hi Dave, >>>> >>>> This looks interesting, definitely chat about it this week. In the mean >>>> time, you could try pointing your client at the Simple SWORD Server: >>>> >>>> https://sword-app.svn.sourceforge.net/svnroot/sword-app/sss/trunk/ >>>> >>>> I'm very close now to a draft of the spec to be implemented against. I >>>> don't think anything there precludes the API being used as described in >>>> your previous email. I think the SWORD and GData approaches are >>>> compatible, but would be good to test properly. >>>> >>>> See you at dev8d! >>>> >>>> Cheers, >>>> >>>> Richard >>>> >>>> >>>> On 14/02/11 16:38, David Tarrant wrote: >>>>> All, >>>>> >>>>> Further to my actual playing with some early implementations, myself and >>>>> Tim Brody have today extended early ideas to be closer to the Google Docs >>>>> extensions and thus produced a client as a test of the implementation. >>>>> >>>>> The whole thing is best demonstrated by the video which is here: >>>>> >>>>> http://www.eprints.org/software/training/3.2/videos/swordv2_eprints.ogv >>>>> >>>>> Things we have working: >>>>> >>>>> CREATE : Initial create of the object >>>>> RETRIEVE: Obviously >>>>> UPDATE: 2 way update between both client and repository >>>>> DELETE: Again 2 way. >>>>> >>>>> Additionally, Metadata can be updated to the edit-uri (also demonstrated). >>>>> >>>>> All of this uses the Edit-URI, Atom:ID and Edit-Media URIs only + the >>>>> contents URIs for handling multiple documents. >>>>> >>>>> All the update requests are backed with HEAD requests to see if content >>>>> has changed and on which side (repo or local). >>>>> >>>>> Do take a look at the video and give feedback. I think this is close to a >>>>> full SIMPLE implementation of SWORDv2, e.g. without on behalf of and >>>>> other complex headers. >>>>> >>>>> The next thing to look into is how to move the object through the >>>>> workflow. >>>>> >>>>> See people at Dev8D where I can do a live demo. >>>>> >>>>> Dave T >>>>> >>>>> >>>>> >>>>> ------------------------------------------------------------------------------ >>>>> The ultimate all-in-one performance toolkit: Intel(R) Parallel Studio XE: >>>>> Pinpoint memory and threading errors before they happen. >>>>> Find and fix more than 250 security defects in the development cycle. >>>>> Locate bottlenecks in serial and parallel code that limit performance. >>>>> http://p.sf.net/sfu/intel-dev2devfeb >>>>> >>>>> >>>>> >>>>> _______________________________________________ >>>>> Sword-app-techadvisorypanel mailing list >>>>> Sword-app-techadvisorypanel@lists.sourceforge.net >>>>> https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel >>>> >>>> >>>> >>>> ------------------------------------------------------------------------------ >>>> The ultimate all-in-one performance toolkit: Intel(R) Parallel Studio XE: >>>> Pinpoint memory and threading errors before they happen. >>>> Find and fix more than 250 security defects in the development cycle. >>>> Locate bottlenecks in serial and parallel code that limit performance. >>>> http://p.sf.net/sfu/intel-dev2devfeb >>>> _______________________________________________ >>>> Sword-app-techadvisorypanel mailing list >>>> Sword-app-techadvisorypanel@lists.sourceforge.net >>>> https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel >>> >> >> > ------------------------------------------------------------------------------ Colocation vs. Managed Hosting A question and answer guide to determining the best fit for your organization - today and in the future. http://p.sf.net/sfu/internap-sfd2d _______________________________________________ Sword-app-techadvisorypanel mailing list Sword-app-techadvisorypanel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel
