This is a comparison of the current REST API and the proposed Alternative REST API. Included in the current REST API are methods newly-implemented for version 3.3 (but not yet documented) as listed in JIRA issues for 3.3. Only those methods in the proposed REST API are included where there is either a correspondence with the current REST API or where the URL syntax is similar (ie may conflict with the current REST API). The corresponding SOAP API and LITE API methods are also included for reference.
E&OE - this is a work in progress and would benefit from another pair of eyes to cross-check...
SOAP API
|
Current REST API
|
verb
|
Proposed REST API
|
verb
|
Notes
|
LITE API
|
verb
|
findObjects |
/objects |
GET |
|
|
(1) |
/search |
GET |
resumeFindObjects |
/objects |
GET |
|
|
(1) |
/search?sessionToken={sessionid} |
GET |
ingest |
/objects/{pid}
|
POST |
|
|
(2) |
|
|
(create empty object) |
|
|
/objects |
POST |
|
|
|
(create empty object with given pid) |
|
|
/objects/{pid} |
PUT |
|
|
|
purgeObject |
/objects/{pid} |
DELETE |
/objects/{pid} |
DELETE |
|
|
|
getObjectProfile |
/objects/{pid} |
GET |
/objects/{pid}/properties |
GET |
(4)'(5) |
/get/{pid} |
GET |
modifyObject |
/objects/{pid}?{properties to modify} |
PUT |
/objects/{pid}/properties/property |
PUT |
(3) |
|
|
listDatastreams |
/objects/{pid}/datastreams |
GET |
|
|
(1) |
/listDatastreams/{pid}[/{dateTime}
] |
GET |
purgeDatastream |
/objects/{pid}/datastreams/{dsid} |
DELETE |
/objects/{pid}/datastreams/{dsid} |
DELETE |
|
|
|
getDatastream |
/objects/{pid}/datastreams/{dsid} |
GET |
/objects/{pid}/datastreams/{dsid}/properties |
GET |
(4)'(5) |
|
|
addDatastream |
/objects/{pid}/datastreams/{dsid} |
POST |
/objects/{pid{/datastreams/{dsid}/[withControlGroup/{cg}
] |
PUT |
(4) |
|
|
modifyDatastreamByReference |
/objects/{pid}/datastreams/{dsid} |
PUT |
/objects/{pid}/datastreams/{dsid}/properties/contentLocation |
PUT |
(4)'(6) |
|
|
setDatastreamState |
/objects/{pid}/datastreams/{dsid}?dsState={state} |
PUT |
/objects/{pid}/datastreams/{dsid}/properties/{property} |
PUT |
(3) |
|
|
setDatastreamVersionable |
/objects/{pid}/datastreams/{dsid}?versionable={true | false} |
PUT |
/objects/{pid}/datastreams/{dsid}/properties/{property} |
PUT |
(3) |
|
|
getDatastreamDissemination |
/objects/{pid}/datastreams/{dsid}/content |
GET |
/objects/{pid}/datastreams/{dsid} |
GET |
(3) |
/get/{pid}/{dsid} |
GET |
getDatastreamDissemination |
/objects/{pid}/datastreams/{dsid}/content?asOfDateTime |
GET |
/objects/{pid}/datastreams/{dsid}/versions/timestamp/contents |
GET |
(3)'(7) |
/get/{pid}/{dsid}/{dateTime}
|
GET |
compareDatastreamChecksum |
/objects/{pid}/datastreams/{dsid}?validateChecksum=true |
GET |
|
|
(2) |
|
|
export |
/objects/{pid}/export |
GET |
|
|
(2)'(8) |
|
|
listMethods |
/objects/{pid}/methods |
GET |
/objects/{pid}/methods |
GET |
|
/listMethods/{pid}/{dateTime}
[] |
GET |
(list methods in sdef) |
/objects/{pid}/methods/{sdef} |
GET |
|
|
(1) |
|
|
getDissemination |
/objects/{pid}/methods/{sdef}/{method} |
GET/POST |
/objects/{pid}/methods/{sdef}/{method} |
GET/POST |
|
/get/{pid}/{sdef}/{method}[/{dateTime} |
GET |
getObjectXML |
/objects/{pid}/objectXML |
GET |
/objects/{pid} |
GET |
(3)'(8) |
|
|
getObjectHistory |
/objects/{pid}/versions |
GET |
|
|
(2)'(7) |
/getObjectHistory/{pid} |
GET |
getNextPID |
/objects/nextPID |
POST |
|
|
(2) |
/management/getNextPID |
GET |
describeRepository |
|
|
|
|
|
/describe |
GET |
upload |
|
|
|
|
|
/management/upload |
POST |
getDatastreamHistory |
|
|
/objects/{pid}/datastreams/{dsid}/versions |
GET |
(7) |
|
|
getDatastreams |
|
|
|
|
|
|
|
modifyDatastreamByValue |
|
|
/objects/{pid}/datastreams/{dsid}/contents |
PUT |
|
|
|
Notes
(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
(5) Current REST API lists both properties and values; proposed REST API has separate methods for getting a list of properties and getting a property value; to replace current API method both proposed methods need implementing
(6) Current REST API includes setting datastream properties as well as updating content; proposed version has different methods for content and properties - to replace current API method both proposed methods need implementing
(7) see notes on versions below
(8) Difference between "export" and "getObjectXML" needs clarifying in proposed REST API
Versions and History
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}?afterDateTime=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 more 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.