[ckan-discuss] CKAN package ID debate

[Sean Burlington]

Can I suggest another  option for consideration

continue to use package names - if someone requests a package by a
name that has changed this could result in a 301 redirect to the new
name

This would not require a change to the API, and would allow names to
change without breaking things.

It may be best to use package IDs I'm not sure - just wanted to throw
this into the pot.




On 23 March 2010 18:11, David Read <david.read at okfn.org> wrote:
> We're debating changes to the CKAN API to refer primarily to Package
> IDs instead of Package Names. Read on below and please do contribute
> your thoughts.
>
> David
>
> Users can interact with CKAN packages through the REST API by
> referring to packages by name. Names don't change much, but we do want
> to support mutability of this field, and so we're looking at using IDs
> to refer to packages in the API instead, since these definitely don't
> change, even when we start syncing packages across multiple CKAN
> instances.
>
> Examples of current use of package name in API:
> Asking the API for a list of packages: ['aiddata-china', 'naptan',
> 'water-voles-uk']
> Read a package: api/rest/package/aiddata-china returns
> "{'name':'aiddata-china', 'title':'Aid data for China', ...}"
> Search returns a list of matching packages: ['aiddata-china',
> 'naptan', 'water-voles-uk']
>
> Although the 'title' field is best for human reading, you may want to
> change the package's name for a few reasons. It may appear in a URL
> somewhere and it for various reasons may need to reflect the content.
> e.g. 'water-voles-2006-09' may be better as 'water-voles' when it
> becomes clear that the dataset will be updated in future years. Also
> we may want to change 'osm' to 'open-street-map' to disambiguify when
> another package with those initials comes along, or they change their
> name to 'OpenMap' because of a legal dispute with OSM Inc, and are
> keen to change all references.
>
> But there are advantages of using names in the API:
> * more human readable
> * aligns CKAN (and datapkg) with apt-get and CPAN, although I get the
> impression those essentially don't allow module names to change
>
> I think we want to therefore switch to using IDs. Dealing in names as
> well is a 'nice to have' and kept perhaps for backwards compatibility.
>
> It's relatively simple to allow users to specify an ID instead of
> names in requests (whilst accepting either). The question is whether
> we return names, IDs or both.
>
> So here are my suggested options:
>
> Option A - Use new URLs that include an API version number. Users
> accessing this new version of the API get back package IDs. e.g.
> /api/rest/2.0/package returns ['0d9ea8d59be5', '44758e5a0f9c', ...]
> We could implement API versioning as suggested in the first answer
> here: http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
>
> Option B - User specifies an option for the return format if he wants
> IDs instead of package names. This could be a URL parameter or HTTP
> header option, although not particularly RESTful.
>
> Option C - Break back compatibility and just return IDs. We are still
> sort of in beta and may not have many API users.
>
> Do let us know if you think I'm on the right track or not.
>
> _______________________________________________
> ckan-discuss mailing list
> ckan-discuss at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-discuss
>



-- 

Sean Burlington

www.practicalweb.co.uk
company number 06427950
vat number 928 0444 24

0791 236 9476