Wiki Markup |
---|
{builder-sidebar:left|collapse=true} This is a comparison of the current [REST API|FCR30:REST API] and the proposed [Alternative REST API|DEV: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 |
...
Current REST API
...
verb
...
Proposed REST API
...
verb
...
Notes
...
LITE API
...
verb
...
findObjects
...
/objects
...
GET
...
...
...
(1)
...
/search
...
GET
...
resumeFindObjects
...
/objects
...
GET
...
...
...
(1)
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
| 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
\\ | 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
| GET | | modifyObject | /objects/\{pid}?\{properties to modify} |
...
PUT
| PUT | /objects/\{pid}/properties/property |
...
PUT
...
(3)
...
...
...
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="235d0add-2d40-4f17-b25a-4626ca20e94f"><ac:plain-text-body><![CDATA[
...
listDatastreams
...
| PUT | (3) | | | | listDatastreams | /objects/\{pid}/datastreams |
...
GET
...
...
| GET | | | (1) |
...
| /listDatastreams/\{pid}\[/\{dateTime} |
...
GET
...
purgeDatastream
...
\\ \] | GET | | purgeDatastream | /objects/\{pid}/datastreams/\{dsid} |
...
DELETE
| DELETE | /objects/\{pid}/datastreams/\{dsid} |
...
DELETE
...
...
...
...
getDatastream
| DELETE | | | | | getDatastream | /objects/\{pid}/datastreams/\{dsid} |
...
GET
| GET | /objects/\{pid}/datastreams/\{dsid}/properties |
...
GET
| GET | (4)'(5) |
...
...
...
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5c9700bc-bcce-4645-95bc-6aa1bd4f38f9"><ac:plain-text-body><![CDATA[
...
addDatastream
...
| | | | addDatastream | /objects/\{pid}/datastreams/\{dsid} |
...
POST
| POST | /objects/\{pid\{/datastreams/\{dsid}/\[withControlGroup/\{cg} |
...
PUT
...
(4)
...
...
...
modifyDatastreamByReference
...
\\ \] | PUT | (4) | | | | modifyDatastreamByReference | /objects/\{pid}/datastreams/\{dsid} |
...
PUT
| PUT | /objects/\{pid}/datastreams/\{dsid}/properties/contentLocation |
...
PUT
| PUT | (4)'(6) |
...
...
...
setDatastreamState
| | | | setDatastreamState | /objects/\{pid}/datastreams/\{dsid}?dsState=\{state} |
...
PUT
| PUT | /objects/\{pid}/datastreams/\{dsid}/properties/\{property} |
...
PUT
| PUT | (3) |
...
...
...
setDatastreamVersionable
| | | | setDatastreamVersionable | /objects/\{pid}/datastreams/\{dsid}?versionable=\{true \| false} |
...
PUT
| PUT | /objects/\{pid}/datastreams/\{dsid}/properties/\{property} |
...
PUT
| PUT | (3) |
...
...
...
getDatastreamDissemination
| | | | getDatastreamDissemination | /objects/\{pid}/datastreams/\{dsid}/content |
...
GET
| GET | /objects/\{pid}/datastreams/\{dsid} |
...
GET
| GET | (3) |
...
| /get/\{pid}/\{dsid} |
...
GET
...
getDatastreamDissemination
| GET | | getDatastreamDissemination | /objects/\{pid}/datastreams/\{dsid}/content?asOfDateTime |
...
GET
| GET | /objects/\{pid}/datastreams/\{dsid}/versions/timestamp/contents |
...
GET
| GET | (3)'(7) |
...
| /get/\{pid}/\{dsid}/\{dateTime} |
...
GET
...
compareDatastreamChecksum
\\ | GET | | compareDatastreamChecksum | /objects/\{pid}/datastreams/\{dsid}?validateChecksum=true |
...
GET
...
...
...
(2)
...
...
...
export
...
| GET | | | (2) | | | | export | /objects/\{pid}/export |
...
GET
...
...
| GET | | | (2)'(8) |
...
...
...
listMethods
| | | | listMethods | /objects/\{pid}/methods |
...
GET
| GET | /objects/\{pid}/methods |
...
GET
...
| GET | | /listMethods/\{pid}/\{dateTime} |
...
GET
...
]]></ac:plain-text-body></ac:structured-macro>
...
(list methods in sdef)
...
\\ \[\] | GET | | (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="aeb27e14-acef-4feb-8afe-96ab5386991b"><ac:plain-text-body><![CDATA[
...
getDissemination
...
| GET | | | (1) | | | | 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
| GET | | getObjectXML | /objects/\{pid}/objectXML |
...
GET
| GET | /objects/\{pid} |
...
GET
| GET | (3)'(8) |
...
...
...
getObjectHistory
| | | | getObjectHistory | /objects/\{pid}/versions |
...
GET
...
...
| GET | | | (2)'(7) |
...
| /getObjectHistory/\{pid} |
...
GET
...
getNextPID
| GET | | getNextPID | /objects/nextPID |
...
POST
...
...
| POST | | | (2) |
...
| /management/getNextPID |
...
GET
...
describeRepository
...
...
...
...
...
...
/describe
...
GET
...
upload
...
...
...
...
...
...
/management/upload
...
POST
...
getDatastreamHistory
...
...
...
| GET | | describeRepository | | | | | | /describe | GET | | upload | | | | | | /management/upload | POST | | getDatastreamHistory | | | /objects/\{pid}/datastreams/\{dsid}/versions |
...
GET
| GET | (7) |
...
...
...
getDatastreams
...
...
...
...
...
...
...
...
modifyDatastreamByValue
...
...
...
| | | | getDatastreams | | | | | | | | | modifyDatastreamByValue | | | /objects/\{pid}/datastreams/\{dsid}/contents |
...
PUT
...
...
...
Notes
| PUT | | | | h2. 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 |
...
Versions and History
...
API h2. Versions and History [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}?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. |