Steve, Thanks for doing this analysis. I have had my head in code all week and am trying to get up to speed on this. I'm afraid I won't be able to give it proper mental attention before the committer call, but I think your basic point makes sense:
If we are moving toward the Proposed REST API, and the goal of the Stabilization effort for 3.3 is to ensure we don't have to make backward-incompatible changes to get there, some resolution where conflicts exist must be done. Since we've only got a week 'till code freeze, and most US-based developers will be on holiday for a couple days of that, I don't think there is enough time to properly discuss and address some of these inconsistencies. If we want to consider the current REST API stable for 3.3 (and not make back-incompatible changes to it), and still hit the 3.3 release date, that leaves us with the option of doing the Proposed REST API at a different URL endpoint in the future. In other words, we still have the option of wholly deprecating the existing REST API, with proper notice to users of it, but we could introduce a better/stronger/faster alternative alongside it in the future. Regarding asOfDateTime vs. /versionDate, it's interesting to note that the current REST API puts this in a URL parameter rather than in the path as it was originally in API-A Lite. And the Proposed REST API goes back to putting it in the path, effectively bringing it back as more formal "Resource". I'm ok with having it as a parameter or in the path, but I am curious why Asger's proposal puts it back in the path. Is it simply a syntax preference or an intent to turn datastream versions into first-class entities? Regarding documentation improvements on the meaning of the dateTime parameter (whatever the syntax), I agree, it should be more explicit. - Chris On Sat, Nov 21, 2009 at 2:49 PM, Steve Bayliss <[email protected]> wrote: > We have Asger's proposal on an alternative REST API which has received good > support. FCREPO-543 is for stabilisation of the REST API, such that after > this is done there will not be any backward-incompatible changes. > > I'm making an assumption that stabilisation of the REST API includes the > adoption/implementation of the URL syntax in Asger's proposal for the cases > where: > > 1) there are existing REST API calls that do not conform to Asger's proposed > syntax; these should probably be modified to use the new syntax > 2) there are existing REST API calls that are not yet included in Asger's > proposals; these should probably be reviewed and revised to conform to the > general syntax that Asger proposes > > This would be to ensure that the REST API URLs do not have to change in the > future as more of the alternative REST API methods get implemented. > > If that assumption's not correct then most of the following can be > ignored... > > As an attempt to see where we are with this and to help work out where we > want to go, I've put together a table of existing REST API calls (including > ones being introduced in 3.3), their equivalents in Asger's proposal, > together with a correspondence to the LITE API and the SOAP API methods. > > This is at > http://www.fedora-commons.org/confluence/display/DEV/Current+and+Proposed+RE > ST+API+comparison > > It could do with cross-checking; it's based on the current API > documentation, Asger's proposal on the wiki, and JIRA issues down for 3.3. > > I've attempted to highlight where there are discrepancies between the > current and proposed alternative REST API, these seem to fall into the > following categories: > > (1) Present in current REST API but not in proposed REST API - leave current > REST API version as-is, syntax conforms to proposed REST API > (2) Present in current REST API but not in proposed REST API - > implementation and URL syntax needs defining to conform to proposed REST API > (3) Present in both current REST API and proposed REST API but URL syntax > differs - proposal: change to use proposed REST API syntax > (4) Present in both current REST API and proposed REST API but definition > differs - resolution needed > > There are some more detailed issues (eg where there's not a one-to-one > correspondence) that I've listed as well (this includes the granular setting > of individual properties vs a single call to set several properties in one > go) > > > Versioning and History > ====================== > > http://www.fedora-commons.org/confluence/display/FCR30/Versioning describes > Versioning in Fedora. Both this and the API documentation talk about > retrieving the state of a digital object or datastream at a point in time. > Under-the-hood Fedora manages versioning of datastreams by creating copies, > versions, with an explicit datastream version identifier and the timestamp > of the modification. > > We have identifiers for objects and datastreams, and the ability to retrieve > the state of these objects at a particular time - but so far versions have > not really been made explicit as identified resources, rather the ability to > retrieve resources as of a point in time has been provided. > > I think the proposed REST API could be moving away from this (or at least > could be ambiguous) by including a timestamp in "version" URLs - The syntax > ... /versions/{timestamp} ... suggests an explicit identifier for a version, > rather than identifying the state of the object at a particular time. > (Furthermore, if a datastream was modifed at times t1 and t2, then URLs > including timestamp t such that t1 <= t < t2 will all retrieve the same > content -- effectively there is now a range of URLs for the same "version".) > > I'd propose that we: > > 1) Standardise on a URL parameter of "asOfDateTime" for all REST API methods > to make explicit that it is the state of an object at a particular timepoint > that is being referred to (so: GET > /objects/{pid}/datastreams/{dsID}?asOfDateTime=xyz); or > 2) Change the "version" component of the URL to "versionAt" (or something > similar) to be more explicit. > > My preference would be for (1). > > Similarly, I would propose that the methods that retrieve an object's > history (URLs ending in /versions) should be made explicit in that they are > retrieving the points in time that an object was changed, rather than > retrieving version identifiers. I would propose changing these URLs to > /history. > > (In fact the semantics are maybe a little vague in definition - if a > datastream is modified at time t, then the actual state of the datastream > "at" time t could be ambiguous: is it in the state before the modification > is made, the state after the modification made, or is it in a "being > modified" state? In fact the API methods retrieve the state after the > modification. The documentation includes "... a version of the digital > object at the specified point in time ..." and "[asOfDateTime] ... > specifying the desired version". Maybe the documentation could be made a > bit more explicit, in that "asOfDateTime" means the state including any > modifications made at that dateTime.) > > Regards > Steve > > > ------------------------------------------------------------------------------ > Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day > trial. Simplify your report design, integration and deployment - and focus on > what you do best, core application coding. Discover what's new with > Crystal Reports now. http://p.sf.net/sfu/bobj-july > _______________________________________________ > Fedora-commons-developers mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/fedora-commons-developers > ------------------------------------------------------------------------------ Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day trial. Simplify your report design, integration and deployment - and focus on what you do best, core application coding. Discover what's new with Crystal Reports now. http://p.sf.net/sfu/bobj-july _______________________________________________ Fedora-commons-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/fedora-commons-developers
