Standard format for returning errors?

[Vance Lucas]

Hey everyone. I've been studying Hypermedia APIs and lurking on this mailing list for a while now, so now it's time to contribute.

I am currently building a Hypermedia API service for a startup of my own based on HAL + JSONSchema for forms, and I am wondering if there are any suggestions for standard error response structures? I think there are a few cases that have to be considered:

1. Creating or updating a resource (400)
2. General application error (401, 403, 500, etc.)
   
3. Others?

My current structure looks something like this:

(1) Resource creation or update

{

  errors: {

     name: [ 'Required field \'name\' was left blank' ],

     date_start: [ 'Required field \'date_start\' was left blank' ]

   }

}

(2) General application errors (403 in this case)

{

  error: 'Forbidden'

}

I was thinking about unifying the structures somehow so I would not have two different formats, but I'm not quite sure how. Has anyone else done any work on this?

[Jon Moore]

> (1) Resource creation or update
> {
> errors: {
> name: [ 'Required field \'name\' was left blank' ],
> date_start: [ 'Required field \'date_start\' was left blank' ]
> }
> }

An interesting idea here is to potentially return the content that
would have been returned by a GET to that (or another) resource,
perhaps with a human-readable error description embedded in a known
location in it. Think of this as an extension of the hypermedia "path"
through the application state. Instead of a dead-end ("400, do not
pass Go"), the client gets "that didn't work and here are some options
for what you may want to do next" (remember to set Content-Location
appropriately).

In the case of a 409 (or potentially 412) error response to an update,
returning the current state of the resource may save network
round-trips, for example.

Jon
........
Jon Moore

[mca]

i use the following standard way of reporting errors over HTTP:

title

description

internalCode

linkForMoreInformation

this can be expressed in any format (XML, JSON, HTML, text, etc.).

In the few cases where I design the actual media type, these elements are included. In cases where I use existing media types (HTML, Atom, etc.), I add these using microformats or any other vehicle appropriate for that type.

Finally, you might want to check out Mark Notingham's proposed RFC to standardize reporting problems over HTTP[1].

[1] http://tools.ietf.org/html/draft-nottingham-http-problem-01

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Darrel Miller]

You might also want to consider this
https://github.com/blongden/vnd.error which is another ongoing effort
to crack this particular nut.

Darrel