[ckan-discuss] API For Package Name

Wed Nov 24 15:28:42 GMT 2010

Hi Richard,

Thanks for your email. It was great to meet you in person last week.

Richard Cyganiak wrote:
> The CKAN API is indeed very nice. It's not very RESTful though. RESTful 
> APIs use hyperlinks to point to related resources. The CKAN API doesn't 
> use hyperlinks but refers to related resources by group name, revision 
> ID, or package name instead.
> 
> In that spirit, wouldn't it be more appropriate to have a complete 
> package URL as the response data format of this call?
> 

Yes, this is an area I'd really like to sort out. The API is not very 
hypermedia-driven at the moment. Although in the Form API we do indeed 
return a 201 Location header after domain objects are created, we don't 
do this in the Model API (yet!).

As you say, there are a number of aspects for us to consider. Perhaps we 
could go right back to the start, and look at the package register? At 
the moment it returns a list of package IDs (or package names in API 
Version 1). I'm detecting that you'd slightly prefer a list of absolute 
URLs. :-)

Please forgive me, but recently I have been unable to decide whether or 
not the IDs can be treated as relative URLs, with the locator of package 
register (somehow) as the base URL? What do you think about that? Is 
there a definitive answer?

Wikipedia says, "If it is likely that the client will want to access 
related resources, these should be identified in the representation 
returned, for example by providing their URIs in sufficient context, 
such as hypertext links." There are identifiers. Are we missing the 
"sufficient context", or is that provided by the published resource 
locator templates? I really don't know. I've seen some discussions about 
it being okay given that the locator templates are published. But I 
wasn't totally convinced. :-)

So, if we prefix each with the package registry locator, then the 
message size goes up, but probably to no more than double. So that's 
okay? And given the deliberate redundancy, it may be more susceptible to 
compression than the average message.

Is that the sort of thing you'd like to see? We could make a list.

The API is versioned, so we could develop all this into Version 3.

Best wishes,

John.

> Best,
> Richard
> 