Relationship management in RESTful web services - Part I

CollectionSpace offers various RESTful web services for managing meta data for physical/digital objects. Defining RESTful interfaces for various entities in the system is straight forward. Create, Read, Update, Delete, List and Search (CRUDLS) operations on these entities could be easily be mapped to the POST (create), GET (read, list and search), PUT (update) and DELETE (delete) methods of HTTP. For example, see the RESTful APIs for the Role service.

CollectionSpace also has a requirement to support relationships between several entities. For example, there could be one to many relationship between a collection object and a loan object. On a more domain-agnostic side of the services, a permission might be for one or more roles and a role might be related to one or more permissions. Implementing relationships between the RESTful resources is not so straight forward and might need some due diligence. Let's take each of the above two use cases to model relationships in two different ways and talk about pros and cons of each. The two approaches are :

1. Relationship as a first-class RESTful resource
2. Relationship as a sub-resource

I'll cover only the first part in this entry. Feel free to comment on the blog if you have implemented relationships in different and better way.

Relationship as a first-class RESTful resource With this approach, relationship becomes a RESTful resource that supports CRUDLS operations. It is a bit unintuitive to think about relationships like this but it is the most flexible approach. Here, each relationship meta data has the following components:

• Object of the relationship
• Subject of the relationship
• Type of the relationship

For example, a relationship between a collection object entity and a loan entity in English could be:

The object in the relationship is the collection object entity and the subject of the relationship is the loan entity. The types should be namespace qualified. This is derived from the RDF model but perhaps only in parts. The relationship web service would support the following methods :

The advantage of such a data structure is that one can relate anything to anything without worrying about semantics. It is also the biggest disadvantage. Relationship being a first-class RESTful resource, each relationship has a distinct id of its own using which it could be retrieved and updated. However, there are many problems.

1. Unlike the RDF model, the predicate is missing, so it is hard to machine learn how entities are related. The web service would have to do a lot of validation to make sure semantically the relationships are possible between the given entities and are correct.
2. It is not possible to determine cardinality in the relationship
3. If RESTful URIs are used, there is no need to provide separate type and id. For example, http://collectionspace.org/services/collectionobjects/814ed9d4-3315-44fc-993b would uniquely identify the object in this relationship.

I'll cover the 2nd approach in my subsequent blog entry.