[ckan-dev] API docs update

[Adrià Mercader]

Hi

On 5 February 2013 18:51, Sean Hammond <sean.hammond at okfn.org> wrote:
> Hey, I've started updating the API docs for CKAN 2.0, pull request here:
>
> https://github.com/okfn/ckan/pull/358

Great stuff Sean


> 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?
I think that the Search API could be deprecated, as package_search and
resource_search are implemented as actions. It has methods not
available to v3 like revision_search, but these could be implemented
later if really needed.
I'm not sure about the Util API though, as it has methods like munge
and is-slug-valid which I'm not sure are still used on the frontend
(there are actions for the autocomplete ones). If they are not used,
again I would deprecate and create actions if needed.


> 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 would like to keep actions namespaced, in case we want to add a new
feature in the future, but I don't have strong feelings about it


> 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.
I think they are still useful as examples, even if out of date. We
should just put a big warning on top "We don't maintain these and may
be out of 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).
I personally never use it, as like you say I find easier calling the
API directly, but the truth is that ckanclient is widely used.
I think it would be great if we could involve the community somehow to
help maintaining it. In any case any feedback from external users will
be appreciated

> Also I'm not sure how well ckanclient supports
> the action api.
I don't think it uses it at all

> 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.
Agree. It is unlikely that someone from the core team will get enough
time to do it in short term though



> 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?
I think is just a matter of semantics, after all all API that you
mention have the same endpoint (ckaninstance.org/api), eg the
DataStore Data API are just action calls.
But I guess that ideally everything should go through the logic layer
(so live in /api/action)


Adrià


>
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev
> Unsubscribe: http://lists.okfn.org/mailman/options/ckan-dev