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 CRUB 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.

General principles

...

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}\]
Contents: The initial contents of the datastream, if any

Creates a new datastream in the object with controlgroup X or {cg} if specified. Datastream is either empty or with the initial content

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-namemethodName}/tofrom/{objpidsdef}

Add a literal relation

?params

Datastream resources

Get Contents of a datastream

GET Wiki MarkupPUT /objects/\{pid}/relationsdatastreams/\{rel-name}/toLiteral/\{value}\[/withType/\{type}\]

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 Wiki MarkupPUT /objects/\{pid}/datastreams/\{dsID}\[/withControlGroup/\{cg}] Contents: The initial contents of the datastream, if any

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

...

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}

...

PUT /objects/\{pid}/datastreams/\{dsID}/relations/\{rel-name}/toLiteral/\{value}\[/withType/\{type}\]

...

Delete methods

Remove a content model from this object

DELETE /objects/{pid}/datastreamscontentmodels/{dsID}/relations/{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 object

DELETE GET /objects/{pid}/datastreams/{dsID}/versions

Get the contents of a specific version of a datastream

Purge a relation to an object

DELETE GET /objects/{pid}/datastreamsrelations/{dsIDrel-name}/versionsto/{timestampobjpid}

Get the versioned properties of a specific version

Delete a literal relation

DELETE GET /objects/{pid}/datastreamsrelations/{dsIDrel-name}/versionstoLiteral/{timestampvalue}/properties

Get a specific versioned property of a specific version

Delete a datastream

DELETE GET /objects/{pid}/datastreams/{dsID}/versions/{timestamp}/properties/{propertyname}

Get the relations of a specific version

Purge the object from the repository

Purge a relation from the datastream

DELETE GET /objects/{pid}/datastreams/{dsID}/versionsrelations/{timestamprel-name}/relationsto/

Method-Centric methods

List the methods on an object

{objPid}

Purge a literal relation from a datastream

DELETE GET /objects/{pid}/methods
Return: a list of objects

Invoke a method on an object

GET/POST /objects/{pid}/methods/{methodName}/from/{sdef}?params datastreams/{dsID}/relations/{rel-name}/toLiteral/{value}