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
