[ckan-dev] #2433 API version 3 changes

[Sean Hammond]

On Fri, May 25, 2012 at 04:32:53PM +0100, Toby Dacre wrote:
> reported issue
> ===========
> According to the documentation, the APIs version 2 and 3 should return id's
> as references.
> Therefore, I changeg 'if api == 2...' to 'if api >= 2...' to select 'id' as
> the returned reference.
> ===========
> 
> 
> Actually the docs aren't clear about version 3 unless I'm being dim.  It
> would seem sensible to make this change however it does change how the
> Action API behaves and as a consequence breaks several tests (at least 4) -
> these are simple to fix we get the id not the name.
> 
> the affected actions
> ===============
> package_list
> package_relationship_create
> revision_show
> group_list
> package_update_validate
> 
> It would be nice to get this fixed and I'm loathed to suggest adding a
> version 4 hack.
> If we make this change it will break things for existing users.  This
> behaviour has existed since the action api was added as far as I'm aware
> 
> links: http://trac.ckan.org/ticket/2433 from pull request
> https://github.com/okfn/ckan/pull/5
> 
> So should we
> a) leave it forever and document
> b) break things and fix it - when 1.7.1 or 1.8?
> c) a magical solution

Leave it and document. I don't see any reason to make this change, it'll
break things for existing users and as far far as I can see there's no
advantage to returning IDs over names, names are friendlier and are (or
should be) accepted by the API anywhere that an ID is accepted. API
functions that won't take a name in place of an ID should be fixed.

It is bad in terms of the user interface that the API functions all
require an "id" parameter but what you actually pass to them is the
"name", but I've documented that in each function's docstring.