Specify Error Schema

[MichaelHirn]

We already got two Schema specification, based on our JSON API design specification (which you may review). But one schema that would really improve our API standard is an Error specification and schema, which could be easily plugged into to all our blueprints, thanks to hercule.

[hobofan]

I think errors should be usual objects and are in the end up to the service.

A general recommendation for a error format:

{
  "type": "error",
  "id": "359f0839-81a4-4404-9d0b-25b3826840ac", // same as the X-Request-Id header, to help track down errors
  "status": 200, // the HTTP status code
  "title": "invalid attribute", // short description of the error
  "detail": "Attribute 'size' should be smaller than 10" // Detailed error description
}

Clients should not depend an the id attribute existing, since for 5xx errors, the response might come from a loadbalancer, which can't dynamically insert the request-id.

[MichaelHirn]

Looks pretty solid to me but I find the naming a bit unconventional. I think we should rely a bit more on common error handling.

What if we rename detail to message?

And title seems to refer to common(?) exception types. I think we should not use this as a short description but rather return one of a specified set of types - which modules might expand as needed. But type is already taken for this so I can think of two possible solutions.

• "type": "error.invalidAttribute"
• "type": "error", "exception-type": "invalidAttribute"

I think title is again a bit too unconventional.

A short set of predefined exception types could make error handling more easy, for both humans and machines.

[hobofan]

What if we rename detail to message?

Sounds okay. I think detail is the more precise naming, but message seems to be the convention, so we'll go with that.

"type": "error.invalidAttribute"
"type": "error", "exception-type": "invalidAttribute"

I don't think that it should be included in type, because that would probably require more specialized parsing logic.
code seems to be the standard name for a exception-type attribute, and seems more accurate (exception implies an error on the application side). The code should also be snakecased unlike your example. ;P

Even with a code attribute, I would keep title. The combination of title and message should give enough information to create an error notice in enduser-facing APIs, where I think message alone might not always be sufficient.

[MichaelHirn]

Good call on code and snake case ;)

But I am still a bit troubled with code and title or at least I do not see the benefit here, yet. code != title, right? They could have different content. Whereas the content of code is quite clear (but I still think we need a common set of values like unauthorized, invalid_attribute, ...) title is not and I can't really think of a scenario where a mix of code + message would not be sufficient. title seems a bit redundant to me right know. I also think about the cost of specifying special title errors, which would be quite unique and therefore hard to document and must therefore be very expressive. But then again, what differs them from message?

Shouldn't we just rely on code + message or can you think of a scenario where title would bring real benefits to the table?

[hobofan]

I'm not quite sure about code either since that is moslty redundant information that can be gotten from the status. A unauthorized code is the same as a 403 status.

Also scrap that "enduser-facing API" part, I completely ignored i18n when I wrote that.

[MichaelHirn]

Right, the HTTP Status Codes would pretty much cover all the "error types", so we could really skip that.

But I think we can skip title, too. More information about the error could be placed into message and title would be quite obsolete. I can't really think right now about a use case where an additional title would come in handy.

[MichaelHirn]

Ok, I created the new structure for the api-blueprint files with a complete project example that demonstrates best practices and standards. I created a special directory for errors which represent the format we discussed so far. But I will wait with tagging the code as v2.0.0 until you can approve on the error format.