[ckan-dev] API refactoring and changes

Thu Feb 28 11:37:03 UTC 2013

Hi Everyone,

I am currently working on refactoring of the action API and making it more stable. There are a few changes that might be controversial so I'd like you to comment on them at [1]. I will update the comment as I commit code to the branch. Please write your comments in the issue so that it easier for me to keep track of them. Thanks. 

Here is a summary of the changes so far:

---

* Many actions do not produce a server error any more if `limit` and `offset` is a negative integer or no integer at all. Also validation for other parameters. Kind of **breaking** because instead of a 500, you get a 409.
* `ParameterError` was removed in favour of `ValidationError` **breaking**
* `_get_or_bust` goes through the validation code (common code paths)
* `_get_or_bust` returns a list instead of a single string for a missing field (consistent with validate) **breaking**
* Updated docstrings
  * Datastore docs indicate optional parameters
* `current_package_list_with_resources` supports `offset`, `page` is deprecated
* Auto complete actions get consistent parameters, `q` is now required in all auto complete actions **breaking**, all actions support limit
* Added tests for changes
* `[package|resource]search` have proper parameter validation
* small fixes...

There are still many functions that have no proper validation. Often bad input is not tested and adding validation takes time because new validation definitions have to be written. 

One thing to discuss is whether we want to have basic validation for **all** action functions in `controllers/api` instead of in every single action. This would require a parameter schema for every action function. 

---

Best wishes,
Dominik

[1] https://github.com/okfn/ckan/pull/473