

Problem Details for HTTP APIs - bkudria
http://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00

======
shabbyrobe
What if there were two reasons to forbid the request?

~~~
deathanatos
> What if there were two reasons to forbid the request?

Just return the first. Most languages only have support for one error at a
time (think exceptions in Python/C++/Java/C#/…, return codes in C) so
returning more than one error ends up being really difficult to an API: what
do you do? Raise some sort of MultipleErrors exception? (then how do you catch
this?); take the first? (what was the point of multiple, then?)

The same complexity exists on the server-side: you have to maintain some sort
of "errors thus far" state, instead of just doing what is probably the
language-natural thing: raise an exception that'll get translated to JSON.

The only real case I've found for multiple errors is form-field validation,
when multiple fields don't validate. I've found it's sufficient to just bottle
them into a "ValidationError" and return that: it can contain a list of fields
and their issues. The rest of the API can then continue to benefit from a
simpler interface.

------
joosters
Why can't apps modify the original HTTP error message, for example using "403
Not Enough Credit" instead of "403 Forbidden", in their first use case?

~~~
steveklabnik
Strictly speaking, they can, but then you're parsing strings to figure out
what exactly is wrong...

~~~
joosters
It doesn't preclude putting computer-readable data in the body of the
response.

Their example is the error 'You do not have enough credit'. Surely their web
server should be sending '403 You do not have enough credit' and not '403
Forbidden' ?

------
xg15
I like the idea but I wonder how it plays together with "human-friendly" APIs
that return error codes and HTML. Should you use Accept: headers to signify
that you want a machine-readable error message?

~~~
awinder
You could definitely use content negotiation to present human-friendly errors
if you were exposing HTML out of the API itself. But otherwise the concept of
"human friendly" APIs seems a little weird to me. Likewise, the idea that
error codes are more friendly than links to error entities also seems way more
developer- / human-friendly. Random per-application error codes seem like a
really bad idea to me, if you have the need to expose more information about a
group of errors, the right way seems like this approach - link to a common
error object, which itself contains classification details

~~~
xg15
You are right that this is no good idea in the general case. But I think there
are a few endpoints that have "pretty printing" outputs for developers enabled
if text/html is in the accept list. At least the (internal) deviantart API did
have that some time ago.

I agree that the whole thing can be solved nicely with content negotiation.

