[ckan-dev] API docs update

[Sean Hammond]

Hey, I've started updating the API docs for CKAN 2.0, pull request here:

https://github.com/okfn/ckan/pull/358

Questions:

Does the Action API replace the Search API and Util API? There does seem
to be overlapping functionality here, e.g. the search api has
/dataset/search and /resource/search, and the action api has
package_search and resource_search. So should the Search API and Util
API be moved into the Legacy API section along with the rest of the v1/2
api stuff? Or are we promoting the Search and Util APIs alongside the
Action API going forward?

Do we want to let people use e.g. /api/package_show instead of having to
do /api/action/package_show? (but still support the old /action/ URLs
for backwards-compatibility).

I removed the whole "Tools for Accessing the API" section, which
included links to ckanclient and several other ckan api clients written
in other languages. This could be put back, but I figure most of these
clients are probably out of date and we surely can't support that many
api clients in different languages and keep them all up to date.

What do we want to do about ckanclient? Personally I don't like
ckanclient because it introduces errors and then hides the error
messages from the user. In my experience people do much better once you
tell them to just post to the action api from python directly (which is
about 3 lines of python). Also I'm not sure how well ckanclient supports
the action api.

We could sort ckanclient out and update it (or just completely replace
it with a new one) but some dev time would have to be scheduled-in for this.

General comment, why do we have so many APIs? There's the v1/2/3 API,
the Util API, the Search API, the Storage API, and now the DataStore
Data API. Can we not just have one versioned API called the CKAN API and
put all the functions into it?