[ckan-dev] Learning about actions

[Adrià Mercader]

Hi Ryan,

On 22 January 2013 20:47, Ryan Clark <ryan.clark at azgs.az.gov> wrote:
> On Jan 21, 2013, at 10:37 AM, Ryan Clark <ryan.clark at azgs.az.gov> wrote:
>
> What are the advantages of making new actions vs. just using IRoutes to map
> a URL to a python function?

The main advantage of building an action function is that this piece
of functionality will be automatically available to the different
interfaces of CKAN:
* Controllers, template helpers, command line etc from your or other
extensions will be able to access it via `get_action`:

from ckan.plugins import toolkit
result = toolkit.get_action('my_custom_action')(context, data_dict)


* The function will be exposed via the v3 API (Action API)
http://ckaninstance.org/api/action/my_custom_action

It also has the advantage of being more closely tied to the
authorization, you can define a 'my_custom_action' auth function and
load it via the IAuthFunctions interface to control access to this
particular action (see the logic folder in ckan core or
ckanext-harvest to see how this is done).


> I've kind of answered my own question by actually playing around with
> building an action. However, there's still a lot to be curious about.
>
> - Is there any documentation of "best-practices" for the function that
> controls a custom action?
I don't think there is a doc page for this. As a general guidance, all
action functions should get a context and data_dict parameters, and
return a dict with their output.

One important thing to keep in mind, not only for action functions but
for extensions development in general, is that the plugins toolkit
should be used whenever possible. That will make your extension less
likely to break on future CKAN versions. get_action, check_access and
the most common exceptions are included in the toolkit:

http://docs.ckan.org/en/latest/toolkit.html


> - It was interesting to find that the action responses were automatically
> generated, and that the __doc__ was used as "help", allowing some
> self-documentation of the API
> - What do you have to do to make a response "success": "false"? Is there a
> preferred method for returning a 400 when a request is malformed?
Your action function should raise an Exception if you encounter a
problem. The most common ones are included in the plugins toolkit, and
are captured by eg the API controller to return 401, 404, etc:

exception NotAuthorized Exception raised when an action is not
permitted by a user.
exception ObjectNotFound Exception raised when an object cannot be found.
exception ValidationError Exception raised when supplied data is
invalid. it contains details of the error that occurred.


Hope this helps,

Adrià


>
> Thanks!
> Ryan
>
>
>
> ____________________
>
> Ryan Clark
> ryan.clark at azgs.az.gov
> (520) 302-4871
>
>
>
>
>
>
>
>
> _______________________________________________
> 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
>