Subject: [apps-discuss] draft-nottingham-http-problem

From: Michael Stillwell <[email-masked]>
Date: Wed, 6 Mar 2013 22:07:56 +0000

Some questions/thoughts on the "Problem Details for HTTP APIs" draft:

http://tools.ietf.org/html/draft-nottingham-json-home-02

The existing approach to handling problems seems to be for clients to
assume that the combination of a URL (or just domain), a status code,
and a media type determines the type of the body.  So clients will
interpret { flickr.com, 4xx, application/json } in one way, and {
twitter.com, 4xx, application/json } in another.

The draft seems to suggest in effect moving the domain name into the
body of the document itself to form a sort of namespace (i.e. as the
problemType key), so that error types can be shared between different
services.  But I'm wondering just how much sharing is actually
possible in practice.  (This question also applies to the similar
vnd.error proposal https://github.com/blongden/vnd.error.)

An example from the draft is an "out-of-credit" error, but thinking
through the various sorts of "out-of-credit" messages I actually
receive, and how I go about remedying the problem (from phone
companies, hosting providers, public transport providers), I can't
think of very much they share, and certainly very little that would be
able to be acted upon in an automated way that did not require
knowledge of the service that generated them.

(I'm assuming that part of the point of the proposal is to establish
better mechanisms for programmatically dealing with and reporting
problems--if the problem reports were going to be interpreted by
humans then you could simply return text/html with whatever body you
wanted.)

Section 4.1 suggests that more complicated domains would be better
served by application-specific formats, and this seems reasonable,
although I don't think I've ever seen such a thing.  So a problem with
a financial transaction might warrant a special problem format defined
by some banking organisation.  (Though I suppose extremely complicated
domains (mortgage application?) might also return a 201 or 202 status,
and put the actual "error" report somewhere else.)  But there doesn't
seem to be much of a meaningful gap between "complicated" domains that
could do with their own problem media type, and domains where the
existing { domain, status, media type } triple approach works out just
fine.

Cheers,
Michael

---

From: Erik Wilde <[email-masked]>
Date: Wed, 06 Mar 2013 14:34:15 -0800

hello michael.

> twitter.com, 4xx, application/json } in another.

why do you assume this is the case? HTTP status codes are defined by 
HTTP, and they always mean the same for all HTTP interactions, 
regardless of the domain or anything else. if you get a 404, then it 
means what http://tools.ietf.org/html/rfc2616#section-10.4.5 says it 
means, not less and not more.

> vnd.error proposal https://github.com/blongden/vnd.error.)

the idea here is that services have the opportunity to provide 
supplemental information *beyond* the HTTP status code. so yes, this 
supplemental information is now runtime information (i.e., not part of 
HTTP's standard status codes). whether it is *shared* is a different 
issue; it would also be perfectly fine if services always define their 
own problemType URIs, simply for the purpose of providing some 
information that goes beyond what they can communicate through HTTP's 
standard status codes.

sharing of problemType URIs is optional, but it sounds like something 
that may make a lot of sense. for example, when some software is 
deployed, it may choose to always use canonical URIs when sending HTTP 
problem details. clients now could use those problemType URIs to respond 
to these specific errors in a more specific way than to just the vanilla 
HTTP response.

> knowledge of the service that generated them.

you have a point here, but you could also simply consider the case of 
some specific software product always using the same problemType URI for 
its "out-of-credit" error, and then at least all services based on that 
specific software product would share the same problemType URI.

does this explanation sounds reasonbale to you? cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Michael Stillwell <[email-masked]>
Date: Thu, 7 Mar 2013 01:06:33 +0000

Hiya Erik,

Thanks for your reply.

On Wed, Mar 6, 2013 at 10:34 PM, Erik Wilde <[email-masked]> wrote:

>> http://tools.ietf.org/html/draft-nottingham-http-problem-03
> why do you assume this is the case? HTTP status codes are defined by HTTP,
> and they always mean the same for all HTTP interactions, regardless of the
> domain or anything else. if you get a 404, then it means what
> http://tools.ietf.org/html/rfc2616#section-10.4.5 says it means, not less
> and not more.

Ah to clarify this point, all I mean is that under existing practice,
if clients get a response with a 4xx status code, and a media type of
application/json, how they process that response varies according to
the domain it came from.

So I'm not saying that the response can redefine the 428 status code
to mean "image does not contain picture of a cat"--but I think it can
contain machine-readable information that explains how to satisfy the
failed precondition.

> the idea here is that services have the opportunity to provide supplemental
> information *beyond* the HTTP status code. so yes, this supplemental
> information is now runtime information (i.e., not part of HTTP's standard
> status codes). whether it is *shared* is a different issue; it would also be
> perfectly fine if services always define their own problemType URIs, simply
> for the purpose of providing some information that goes beyond what they can
> communicate through HTTP's standard status codes.
>
> sharing of problemType URIs is optional, but it sounds like something that
> may make a lot of sense. for example, when some software is deployed, it may
> choose to always use canonical URIs when sending HTTP problem details.
> clients now could use those problemType URIs to respond to these specific
> errors in a more specific way than to just the vanilla HTTP response.

Maybe an example of the Github API can better illustrate some of the
problems of both sharing and not sharing problemType URIs that I'm
worrying about.

Github's API docs nicely explain how to interpret a their 422 status code:

http://developer.github.com/v3/#client-errors

And so, under the draft, instead of returning "application/json" (I'm
assuming that's what they're returning, they don't actually say), they
would return "application/api-problem+json" (or switch between the two
via conneg).  They then need to decide whether to use their own, or a
shared, problemType.

If they used their own, then clients would need to be Github-specific,
and so this doesn't seem to have much benefit over just returning
"application/json" in the first place and having clients behave
differently based on (in effect) the github.com domain name.

Conversely, whilst it would be nice if Github were able to share a
problemType with other services, I don't think this is easily
achievable.  For example if a field is marked as "invalid", you need
to read the docs to figure out what's wrong (too long? not a
number?)--the problem detail provides no way to programmatically
suggest corrections or fix the request.  It could be enhanced to
provide more useful information, but it's difficult to imagine even a
"create-account" or "add-to-basket" problem details being shared
across services like Amazon, Google, Facebook, and eBay.  Each of
these services has different constraints, and will have
service-specific ways of failing, and so will need different
problemTypes.  Non-shared problemTypes mean non-shared clients, and so
we're back where we started!

Cheers,
Michael

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 7 Mar 2013 14:45:19 +0000

> contain machine-readable information that explains how to satisfy the

Right. This just provides them a way to do that, without having to invent a new format each time. I've seen APIs that define lots of new error media types, something that's nasty and heavyweight. 

> differently based on (in effect) the github.com domain name.

The benefit is that they don't have to invent their own JSON structure, get the right semantics for it, etc. etc. Is that a huge benefit? Not really, but it helps. 

> we're back where we started!

Not quite, but yes, this won't end world hunger. It's a small thing, the real focus is giving help to people who invent their own error formats and trip up in the process (some of the things I've seen really raise the eyebrows, and people spend a *lot* of time trying to get these things right).

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: Michael Stillwell <[email-masked]>
Date: Sun, 10 Mar 2013 13:33:40 +0000

> Not quite, but yes, this won't end world hunger. It's a small thing, the real focus is giving help to people who invent their own error formats and trip up in the process (some of the things I've s…

So if I have this right, the following (fairly minimal) steps are
sufficient for Github to achieve complete compliance with the JSON
version of problem detail:

1. Do conneg on the Accept header.  If the client prefers
application/api-problem+json to application/json, then switch to
"problem detail" mode.  (Hopefully existing clients are already
sending application/json, but if not, servers need to default to
application/json to avoid breaking existing clients.)

2. Add a "problemType" member to the existing response.  At a minimum,
"problemType" could equal
"http://developer.github.com/v3/#client-errors", though a more
specific URI would be preferable.  (Perhaps this can be mechanically
generated from the URI of the request.)

3. Add a "title" member to the existing response.  Would duplicating
the HTTP status be sufficient?

And for GitHub clients to support "problem detail", they only need to
start sending an accept header of application/api-problem+json, and
treat the response as they would application/json.

For some services, wrapping the original application/json response in
something like:

{
  "problemType": "...",
  "title": "...",
  "error": [original_JSON_error]
}

might be preferable/easier for both client and server.

It's good that not minimal work is required by servers or clients to
support application/api-problem+{json,xml} however in the absence of
shared problemTypes the benefits seem correspondingly minimal.  (A URI
to follow seems like it would be useful[1], but Googling the service
and the error is usually good enough.)

And my guess is that shared problemTypes are unlikely to emerge for
the reason that error responses (unlike successes) are usually unique
to the service.  (c.f. the Anna Karenina principle: happy families are
all alike; unhappy families are unhappy in their own way.)

Cheers,
Michael

[1] On the other hand, the fact that few (any?) services currently
provide this, though there are no obstacles to doing so, suggests that
there is limited demand for this feature.