[ckan-discuss] [Fwd: Re: API For Package Name]

John Bywater john.bywater at appropriatesoftware.net
Thu Nov 25 14:14:39 GMT 2010


Hi James,

Thanks for your detailed reply!

James Gardner wrote:
> Hi John,
> 
>>From my point of view it is a different type of thing. 

That's okay, because the Model API, the Form API, and the Search API are 
also different kinds of things. That is, style always works across 
different kinds of things. The function of style is to make independent 
parts cohere as a whole.


> The main use for
> this part of the API (at a different URL so as not to confuse people
> into thinking it is RESTful) is to support JS functions on the
> front-end.

Regarding confusing people:

All the parts of the API have already been described as being RESTful.

And it has already been disseminated that the CKAN API starts at /api.

(By the way, CKAN's *Model* API starts at /api/rest, which needs to be 
repaired. Overcoding it as /api/model is slated for API Version 3. 
Either I should not have written the name 'rest' into the API locator, 
or others could have implemented non-model parts of the API under 
/api/rest. I feel that resources like /api/tag_counts aren't in the best 
place, and I would like us to fix that. If the entire REST API had been 
kept under /api/rest, then we could also have had /api/rpc. That was the 
original purpose of putting 'rest' into the locator. It wasn't 
maintained, probably because it wasn't understood very well. So I'm 
certainly not trying to exclude RPC. However there is in fact nothing 
within the current requirements we have that means we must introduce 
RPC. Hence, lex parsimoniae, we must *not* introduce RPC! The Seach API 
could be much better, but that's another discussion - at least it's in 
the right ball park.)

Therefore, RPC-styled services with /api is an objective confusion.

Regarding supporting JS functions on the front end:

Both tag completion and name munging can just as easily be done in a 
RESTful style, as in an RPC style. On a green field site, I would 
happily do either. However, CKAN is three years old, so it's almost in 
"maintenance mode", and so we should try to work with what we have.

Given that the API has already been styled as a RESTful API, and given 
that CKAN simply doesn't have an RPC API at the moment, the *whole* CKAN 
team should be working to maintain and enhance the RESTful style we 
have. Of course, we can always increase complexity by adding an RPC API, 
it's always been a possibility.

Adding complexity before it is actually needed isn't really a very good 
software engineering style. I'm sure you aren't trying to add complexity 
unnecessarily. But I don't know why, given I have proposed a simpler 
way, it isn't being snapped up.


> As such, the main users will be jQuery developers and the
> standard way to use $.ajax is in an RPC-style with parameters passed as
> query arguments.
> 

So what? There is always a URL, and sometimes there are query arguments. 
My proposal doesn't involve query arguments (but we might still use them 
to invoke JSONP callback). Loads of people use jQuery, and they mostly 
use it the way you describe. But only CKAN's package form needs to get a 
package name from an arbitrary string that is entered by users into the 
title field, and we already have an API that has a particular style.

At the same time, jQuery is great. As well as $.ajax, it provides $.get, 
$.load, $.getJSON, and so on. It also provides $.URLEncode. It has great 
documentation. So we have everything we need on the client side to send 
a title and get a slug, regardless the details of an API.

(By the way, longer term, to support developers using jQuery to do stuff 
with CKAN, we could help by creating and documenting a jQuery plugin for 
the CKAN API, like Flickr. That might make people's lives much easier.)

Anyway, entirely unconstrained by the client-side, the question is, what 
does the server API look like? The choices appear to be:

1.  /api/model/package_name/{string}
2.  /api/util/package/create_slug?title={string}

The best consideration is: which is more maintainable?

I suggest the first is more maintainable, simply because it does not 
involve names of things which do not pertain to getting a package name 
from a given random string. That is, we appear to have no cause to 
involve the names 'create', 'slug', and 'title'. Leaving them out leaves 
less for maintainers to deal with. That consideration should be at the 
heart of everything we do.


> The REST API is nice and so I wanted to keep it separate. 

Thanks. We can incorporate what you've done in the RESTful API.


> In the future
> we may add more JS functionality to the front-end or change the existing
> functionality with more parameters (something that becomes more tricky
> if a RESTful style is adopted for this type of use case).

As I understand these things, that just isn't true. If anything, the 
opposite is true. The whole purpose of the RESTful style is to optimise 
maintainability.

Therefore, from what I've seen, I'm sure we can continue perfectly 
adequately with the RESTful architecture. I'm convinced that's the best 
thing to do.


> The reason for
> having these functions in the API at all rather than in the controllers
> is that we need to be able to call them from catalogue.data.gov.uk which
> only serves the /api path currently. Perhaps in future we can move them
> back there to avoid the issue.
> 

I sympathise. That gives further cause to put this in the existing API.

To recap, CKAN has two interfaces: the Web UI and the API. All of CKAN's 
interfaces use controllers, the API has controllers too.

We don't need to go from two to three interfaces just because we're 
auto-filling the package name field from the package title field in the 
package form (wherever the form is being used ;-) ).

By the way, thanks a lot for fixing up CKAN's CSS and Javascript, so 
that the Form API works better for data.gov.uk. I would be very 
interested to hear details about what has been fixed.

Best wishes,

John.


> Cheers,
> 
> James






More information about the ckan-discuss mailing list