Alternative REST API
Aaron Birkland pointed out a severe, and unrecoverably problem with this proposal. For a versionable datastream, a new version is created for each property or content change. As such, to not make 10 versions with a datastream update, a proper transaction system, or methods that allow you to change all the properties in one invocation is nessesary. For that reason, a modifyDatastream method like in the current API is still required.
In this I will propose an alternative REST api to the one in the Fedora Documentation. It is made to support CRUD (Create, Retrieve, Update, Delete) workflows more natively than the current Fedora APIs. It is based around the idea that every conceivable url should be gettable, and probably puttable. There should not be big methods with lots of parameters, but rather a bunch of small ones resources with very clear purpose. The interface should be usable without any documentation
For CRUD purposes, foxml is not the format of Fedora. Foxml is a very useful and welldesigned storage format, but it is intricate. There will be no ingest or exportToXML methods in this api, as the user should not have to understand foxml. Rather, the Fedora objects is decomposed into resources, available through through URLs.
Table of Contents |
---|
General principles
Content | Location |
---|---|
Objects | /objects/ |
Object presentation | /objects/{pid} |
Object properties | /objects/{pid}/properties |
Object relations | /objects/{pid}/relations |
Object content models | /objects/{pid}/contentmodels |
Datastreams | /objects/{pid}/datastreams |
Datastream | /objects/{pid}/datastreams/{dsID} |
Datastream content | /objects/{pid}/datastreams/{dsID}/content |
Datastream properties | /objects/{pid}/datastreams/{dsID}/properties |
Datasteram relations | /objects/{pid}/datastreams/{dsID}/relations |
Datastream versions | /objects/{pid}/datastreams/{dsID}/versions |
Object Methods | /objects/{pid}/methods |
Method invocation | /objects/{pid}/methods/{methodNamesdef}/from/{sdefmethodName}?params |
...
Create methods
Object resources
Create new object with given pid
...
Return: pid of the new object (/objects/demo:newObject2)
Creates a new, empty object
Datastream resources
Create a new datastream
PUT /objects/{pid}/datastreams/{dsID}[/withControlGroup/{cg}]
Creates a new datastream in the object with controlgroup X or {cg} if specified. Datastream is empty.
Retrieve methods
Object resources
Present Object
GET /objects/{pid}
Return: XML that presents the object....
Undetailed
Purge object
DELETE /objects/{pid}
Get the object properties
...
Example: /objects/demo:myPid2/properties/label
Write a specific property
PUT /objects/{pid}/properties/{property}
Contents: The new value Return nothing, or 404 if property not found. New properties cannot be created.
Get content models for a object
...
Get a list of the content models of this object
Add a content model to this object
PUT /objects/{pid}/contentmodels/{cmpid}
Contents: Nothing
Add cmpid to the list of content model for this object
Get all the relations of an object
...
GET /objects/{pid}/relations/{rel-name}
Return: List of pids of objects referred by this relation
...
List the methods on an object
PUT GET /objects/{pid}/relations/{rel-name}/to/{objpid}
Purge a relation to an object
methods
Return: a list of objects
Invoke a method on an object
GET/POST DELETE /objects/{pid}/relationsmethods/{rel-namesdef}/to/{objpidmethodName}
Add a literal relation
?params
Datastream resources
Get Contents of a datastream
GET PUT /objects/\{pid}/relationsdatastreams/\{rel-name}/toLiteral/\{value}\[/withType/\{type}\] Wiki Markup
Delete a literal relation
dsID}
Get the properties of a datastream
GET /objects/{pid}/datastreams/{dsID}/properties
Get a specific property of a datastream
GET PUT /objects/{pid}/relationsdatastreams/{rel-namedsID}/toLiteralproperties/{valueprop}
Datastream-Centric methods
Create a new datastream
Return: The value
Get the relations of the datastream
GET PUT /objects/\{pid}/datastreams/\{dsID}\[/withControlGroup/\{cg}]
Contents: The initial contents of the datastream, if any Wiki Markup
Creates a new datastream in the object with controlgroup X or {cg} if specified. Datastream is either empty or with the initial content
Delete a datastream
/relations
The RELS-INT block "about" this datastream
Get version timestamps of a datastream
The idea is that the old version of the datastream should support the same getter methods as the current version
GET DELETE /objects/{pid}/datastreams/{dsID}/versions
Purge the object from the repository
...
Get the contents of a specific version of a datastream
GET /objects/{pid}/datastreams/{dsID}/versions/{timestamp}
Update an Inline or Managed Datastream
/contents
Get the versioned properties of a specific version
GET POST /objects/{pid}/datastreams/{dsID}
Contents: The new content of the datastream
TODO (overlaps with create a new datastream...)
...
/versions/{timestamp}/properties
Get a specific versioned property of a specific version
GET /objects/{pid}/datastreams/{dsID}/versions/{timestamp}/properties/{propertyname}
Get the relations of a specific
...
version
GET /objects/{pid}/datastreams/{dsID}/versions/{timestamp}/relations/
Update methods
Object resources
Write a specific property
PUT /objects/{pid}/properties/{prop}
Return: The value
...
property}
Contents: The new value
Return nothing, or 404 if property not found. New properties cannot be created.
Add a relation to an object
PUT /objects/{pid}/relations/{rel-name}/to/{objpid}
Add a content model to this object
PUT /objects/{pid}/contentmodels/{cmpid}
Contents: Nothing
Add cmpid to the list of content model for this object
Add a literal relation
PUT /objects/{pid}/relations/{rel-name}/toLiteral/{value}[/withType/{type}]
Datastream resources
Update the contents of an Inline Datastream
POST /objects/{pid}/datastreams/{dsID}/contents
Contents: The new content of the datastream
Update a datastream property
PUT /objects/{pid}/datastreams/{dsID}/properties/{prop}
Contents: The new value
examples: versionable, state and so on.
Update an External, managed or Redirect Datastream
Contentlocation is just a property of these datastreams
PUT /objects/{pid}/datastreams/{dsID}/properties/contentLocation
Contents: The URL to the contents of the datastream
...
of the datastream
GET /objects/{pid}/datastreams/{dsID}/relations
The RELS-INT block "about" this datastream
Add a relation to the datastream
PUT /objects/{pid}/datastreams/{dsID}/relations/{rel-name}/to/{objPid}
Purge a relation from the datastream
DELETE /objects/{pid}/datastreams/{dsID}/relations/{rel-name}/to/{objPid}
Add a literal relation to the datastream
...
PUT /objects/\{pid}/datastreams/\{dsID}/relations/\{rel-name}/toLiteral/\{value}\[/withType/\{type}]
...
Delete methods
Object resources
Purge object
DELETE /objects/{pid}/datastreams
Remove a content model from this object
DELETE /objects/{dsIDpid}/relationscontentmodels/{rel-name}/toLiteral/{value}
Get version timestamps of a datastream
The idea is that the old version of the datastream should support the same getter methods as the current version
cmpid}
Contents: Nothing
Remove cmpid from the list of content models for this object
Purge a relation to an object
DELETE GET /objects/{pid}/datastreamsrelations/{dsIDrel-name}/versions
Get the contents of a specific version of a datastream
to/{objpid}
Delete a literal relation
DELETE GET /objects/{pid}/datastreamsrelations/{dsIDrel-name}/versionstoLiteral/{timestampvalue}
Get the versioned properties of a specific version
Datastream resources
Delete a datastream
DELETE GET /objects/{pid}/datastreams/{dsID}/versions/{timestamp}/properties
Get a specific versioned property of a specific version
Purge the datastream from the object from the repository
Purge a relation from the datastream
DELETE GET /objects/{pid}/datastreams/{dsID}/versionsrelations/{timestamprel-name}/propertiesto/{propertynameobjPid}
Get the relations of a specific version
Purge a literal relation from a datastream
DELETE GET /objects/{pid}/datastreams/{dsID}/versionsrelations/{timestamprel-name}/relations/
...
toLiteral/{value}