[ckan-discuss] REST API Error Messages

Thu Jul 29 16:13:19 BST 2010

Hi Friedrich,

Friedrich Lindenberg wrote:
> Hi John,
> 
> I just saw your notice on http://okfnpad.org/ckan regarding API error
> messages. The task was inspired by Glen Barnes' recent troubles in
> getting a ruby client to talk to CKAN via the REST API.
> 
> What I would like to change here is three things:
> a) Wrap some of the controller actions in a try/catch and return the
> exception message along with 500 server errors to give clients a clue
> as to what is wrong.
> b) Add extensive logging on the server, including stack traces.
> c) Wrap any error messages returned by the server in a JSON
> dictionary. This makes recognizing them easier for clients
> (essentially, I can still json.loads() them and then check if they
> have an 'error' key) and it allows client to output a more meaningful
> message. It is a bit redundant, though, given that we also return a >=
> 400 status code.
> 
> What's your opinion on these changes? Would they be useful? And: would
> you consider (c) to break the API 1 contract (and have this moved into
> v2)?
> 

Oh, I think it's excellent! Did you see my comment on Glen's ticket?

http://knowledgeforge.net/ckan/trac/ticket/377

"""
Thanks a lot! I totally agree and have already started working on this. 
For example, try pointing your browser to 
http://ckan.net/api/search/revision  (ie without any arguments). Also, 
there is probably a lot less HTML than there was, since the errors are 
not handled as if it was an error within the "Web" user interface. At 
any rate, perhaps we could work through the error cases, filling in the 
tests as we go? I think it's just unworked ground, rather than anything 
deliberate. :-)
"""

There are three things that concern me:

1. Disturbing (or not) the API Version 1. On one hand, I feel we should 
try to avoid disturbing the API Version 1 if possible, because it is 
being used in production Web sites. So, to do it only in API Version 2. 
But we could first try to duplicate the current behaviour in API Version 
1, then implement the better behaviour on the base API class. So does 
that mean we should try to start on the Version 2 tests, then build up 
the Version 2 class?

On the other hand, as well as not having implemented them, I feel that 
we have never specified or documented the behaviour, so should there 
shouldn't be an expectation, and we should feel free to do whatever is 
now wanted to improve the error cases.

2. Putting status in the response body. It's not an terribly strong 
preference, but I'd rather the status was not repeated in the response 
body. But having a single error data format for all error response 
messages would be a fine thing. :-)

3. Validation resources. I wonder whether it might be useful to 
distinguish between true system errors (some of which may occasionally 
reveal sensitive information) from validation error (which could be 
prepared on a case by case basis, and which would be designed not to 
reveal sensitive information). Perhaps true system errors should not be 
disclosed, due to the hazard indicated above. However, we could provide 
validation resources, which would response by listing any errors that 
would mean submitting the data as a create or update operation would not 
succeed. That would repeat the distinction in the Web UI, where nothing 
is revealed about system errors. However, validation errors are 
indicated to guide the user towards a successful submission. The 
system-wide requirement might be: "don't publish system errors to 
users". We could equally send validation errors in responses to create 
messages, but just wrapping the whole method in a try/except and 
returning something about whatever error happens to occur seems a bit 
too indiscriminate.

What do you think about that? :-)

Best wishes,

John.

> Regards,
> 
>  Friedrich