[ckan-discuss] CKAN package ID debate

[Evan King]

I like the 301 redirect suggestion.

Beyond that, I also think the API versioning is something that should happen anyway, could we implement both? 
 


Evan King
evan.king at coi.gsi.gov.uk
 
T: 020 7261 8635
M: 07726628294
COI
Hercules Road
London
SE1 7DU

>>> Sean Burlington <sean at practicalweb.co.uk> 03/24/10 8:38 AM >>> 
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

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




This communication is confidential and copyright.
Anyone coming into unauthorised possession of it should disregard its content and erase it from their records.

The original of this email was scanned for viruses by Government Secure Intranet (GSi) virus scanning service supplied exclusively by Cable & Wireless in partnership with MessageLabs.
On leaving the GSI this email was certified virus free.
The MessageLabs Anti Virus Service is the first managed service to achieve the CSIA Claims Tested Mark (CCTM Certificate Number 2006/04/0007), the UK Government quality mark initiative for information security products and services. For more information about this please visit www.cctmark.gov.uk