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.2 3 (but not yet documented) as listed in JIRA issues for 3.23. 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.
...
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) |
|
| ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5d2f283f91eb8b00-cd656f7b-436d49a8-8da0b67d-e4f2d42c481fe92219e7a651"><ac:plain-text-body><![CDATA[ | 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) |
|
| ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c3cccc976c8149d0-46ad6df2-462943bb-8de49bae-dd71cb113cd8727ff5079ed1"><ac:plain-text-body><![CDATA[ | 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 | ]]></ac:plain-text-body></ac:structured-macro> | |
(list methods in sdef) | /objects/{pid}/methods/{sdef} | GET |
|
| (1) |
|
| ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="26d51d65f301b18d-ee736e17-46de4e4a-aa72b967-88e14581b3076609aeef2ac0"><ac:plain-text-body><![CDATA[ | getDissemination | /objects/{pid}/methods/{sdef}/{method} | GET/POST | /objects/{pid}/methods/{sdef}/{method} | GET/POST |
| /get/{pid}/{sdef}/{method}[/{dateTime} | GET | ]]></ac:plain-text-body></ac:structured-macro> |
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 |
|
|
|
...
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.