[ckan-discuss] CKAN API and relationships

[Richard Cyganiak]

Hi,

In the lodcloud group on the Data Hub we've been for a long time (ab)using extras fields to express relationships between datasets: A field like “links:dbpedia” with value 500 indicates that a dataset has 500 links to the dbpedia dataset.

Rufus and others have encouraged me to look into CKAN's “relationship” feature to turn these pseudo-relationships into proper first-class CKAN objects:
http://wiki.ckan.org/Domain_Model/Package_Relationship

I spent some time looking into this. I found some good news (e.g., relationships can have comments; this gives us a place to store the “500”). But I also ran into some problems – see below.


== Missing relationship type ==

Relationships in CKAN are typed, and the available types are hardcoded:
depends_on dependency_of derives_from has_derivation child_of parent_of

None of these types fit the usage in the lodcloud group. We need another type: links_to.

The current lack of a fitting type is a pretty big roadblock.


== Problems with CKAN API documentation ==

I'm referring to this page:
http://readthedocs.org/docs/ckan/en/latest/api.html#model-api

First, this page is missing the section on “Model formats”, which is a rather essential part of the API documentation. This section disappeared from the documentation between 1.4.2 and 1.4.3. Here's the last version I could find:
http://readthedocs.org/docs/ckan/en/ckan-1.4.2/api/version2.html#model-formats

This table of formats should be restored.

Second, the API documentation lacks information on how to create new relationships. It only states how to inspect and update existing ones. The table here lacks a line:
http://readthedocs.org/docs/ckan/en/latest/api.html#model-methods

The missing line is:

Dataset Relationship Entity | POST | Pkg-Relationship

(If someone can point me towards a source file for this part of the documentation, then I could probably make a patch.)


== Creation of new relationships is not intuitive ==

By trail and error I found that relationships can be created by POSTing to the URL of the desired Dataset Relationship Entity:
/rest/dataset/DATASET-REF/RELATIONSHIP-TYPE/DATASET-REF

It would be more intuitive and more in line with the rest if the CKAN API if relationships could be created by POSTing to the Dataset Relationship Register:
/rest/dataset/DATASET-REF/relationships