[ckan-discuss] CKAN API and relationships

[David Read]

On 23 January 2012 11:44, Richard Cyganiak <richard at cyganiak.de> wrote:
> 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.

Richard,

Many thanks for this. It would be great to get you on board with this
oft-requested but under-used feature. The feedback you've sent is
really useful.

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

Yes, these are designed to be added when good use cases come along
like this, so I will add it. There's an argument for making it
arbitrary, but I think we'll keep it constrained whilst we see how it
gets used.

I'll see if we can easily add a 'count' property for this one, to
store the number of links, otherwise the comment will suffice.

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

This looks like an error during reorganisation of the rst files. I'll
check what happened.

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

The source is here:
https://github.com/okfn/ckan/blob/master/doc/api.rst but don't worry,
I'll fix it as part of the ticket.

> == 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

I agree, and I've had a note to do this for a while. I'll see if it
can be easily changed.

I've put these requests in a ticket http://trac.ckan.org/ticket/1695
and since it should be quick, I'll aim to get these onto the datahub
in the next couple of weeks.

By the way, you may wish to play with these using the version 3 of the
API - we'd be interested in your views. It's RPC style rather than
RESTful. The v1 and v2 APIs remain as RESTful wrappers over calls such
as 'package_relationship_create'. There are still rough edges, such as
500 error if you get don't send the right parameters, but otherwise
we're pleased about the extra feedback it gives. Docs:
http://readthedocs.org/docs/ckan/en/latest/apiv3.html

David

> _______________________________________________
> ckan-discuss mailing list
> ckan-discuss at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-discuss