Problem

In order to consider Fedora's REST API complete, we need to have functional equivalents to API-M's relationship management methods.

This includes the ability to:

• add and remove relationships incrementally
• get a subset of relationships

Approaches

We talked about a couple approaches during the November 3rd Committer Meeting (see notes and audio here).

1. Generic endpoint for updating / querying all relationships in the repository.  This would allow one to update relationships without specifying which object or datastream they resided in explicitly.  There was some concern that this might result in confusion because it sets up the expectation that arbitrary relationships are accepted, but in reality, it would only accept changes that were valid in RELS-EXT and RELS-INT datastreams.
2. Object-specific endpoints for updating relationships on a per-datastream basis.  This approach would require that applications using the API are aware of which objects and datastreams the relationships are asserted in.  While discussing this approach, we noted that this pattern could be followed in a general way to make partial datastream updates possible for other types of datastreams as well.

Strawman Proposal

During the call, we talked most about approach #2, and started to define what it would entail:

1. Define a generic method (or set of methods) for applying partial changes to datastreams.
2. Implement it for RELS-EXT and RELS-INT (RDF-based) so that additions and deletions to those datastreams can be made via SPARQL update.

Example:

• HTTP Verb: PUT
• URL: /objects/{pid}/fedora-system:/updateDatastream?dsID={dsID}&type=sparql-update
• Body: A SPARQL/Update document (UTF-8?) to apply to the datastream
• Successful response:** Code: 201
  • Location header: URL to datastream
• Failed response:** If datastream doesn't exist: TBD
  • If input document is malformed: TBD

Thoughts?

Please feel free to comment on this proposal here or on the dev list.