[ckan-discuss] API For Package Name

[Richard Cyganiak]

Hi John,

On 24 Nov 2010, at 15:28, John Bywater wrote:
> The API is not very hypermedia-driven at the moment. […] 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. :-)

Yes!

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

Good question. Some representation formats, such as HTML (and, in  
fact, RDF!), are designed explicitly for hypermedia, and the format  
specifies which parts of the message are URLs and what base URL they  
are resolved against. That makes the use of relative URLs  
straightforward, which is good for keeping message size down. JSON,  
for all its advantages, unfortunately doesn't know a URL from a string.

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

I think you summed up the trade-off very well. If URLs are included in  
the messages, then less context has to be hardcoded into clients -- I  
wouldn't need to tell the client that the URL for retrieving a package  
representation is obtained by concatenating the returned package ID to  
"http://ckan.net/api/rest/package/". That would simplify the clients,  
and make them more resilient against future change on the server (such  
as a move to a different domain!).

On the downside, message size increases.

Personally, I have a high tolerance for redundancy in messages. A side- 
effect of prolonged exposure to RDF ;-)

A good compromise might be to use URLs relative to the API base URL "http://ckan.net/api/rest/ 
" when referring to resources within messages. So we'd have "package/ 
this" and "package/that" and "group/foo" and "tag/bar" etc.

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

+1!

Best,
Richard



>
> Best wishes,
>
> John.
>
>
>> Best,
>> Richard
>