[ckan-discuss] REST API Error Messages

Sat Jul 31 16:43:25 BST 2010

Hi Glen,

Glen Barnes wrote:
> On 30/07/2010, at 3:13 AM, John Bywater wrote:
> 
> 
>> 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. :-)
> 
> I'm easy either way. Having it repeated in the response body is may be a connivence for developers. I'm guessing less experienced developers have a pretty hard time dealing with response headers. Anything we can do to make things clearer is a good thing.
>   

Okay, so let's not do it. :-) If status were in the error messages, then 
I'm guessing some will then also expect status to be in the normal 
messages, and I don't think we want to go there. :-)

>> 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.
>>
> 
> I agree. I would say system 500 errors should be trapped and not returned in the response body. These should be written to a log and also notified via some service (I prefer Hoptoad, it's cheap and works well). Server logs and/or the notification service should be actively monitored and errors fixed as they are found. The goal should be to eliminate 500 server errors from ever occurring and I agree that these should not be shown to the user. We should respond with a simple json formatted response {"message":"A system error occurred and the developers have been notified" }
> 

Fantastic! So, now we have a good idea about how we want to do this, 
could we possibly reach to going through the broad and clear requirement 
that "CKAN API error messages need fixing up" by identifying individual 
error cases, writing tests, implementing code, and continuing until we 
feel we've got all the corners covered? We could start with exactly what 
tripped you up, Glen, and work out from there? ... What tripped you up 
exactly?

Best wishes,

John.

> 
> 