I'm just catching up here. I fully agree with what Al says about not overloading the edit-media link.
#g -- Alistair Miles wrote: > Hi Richard, > > 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? > > 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)? > > 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. > > 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. > > 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? > > Cheers, > > Alistair > > > [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 >> > ------------------------------------------------------------------------------ Enable your software for Intel(R) Active Management Technology to meet the growing manageability and security demands of your customers. Businesses are taking advantage of Intel(R) vPro (TM) technology - will your software be a part of the solution? Download the Intel(R) Manageability Checker today! http://p.sf.net/sfu/intel-dev2devmar _______________________________________________ Sword-app-techadvisorypanel mailing list Sword-app-techadvisorypanel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sword-app-techadvisorypanel
