Subject: [apps-discuss] Comments on draft-nottingham-http-problem-03

From: Jan Algermissen <[email-masked]>
Date: Wed, 29 May 2013 11:06:23 +0200

Hi Mark,

here are some comments on http://tools.ietf.org/html/draft-nottingham-http-problem-03

Excuse the 'purist mindset driven tone' - you know me, no offence intended :-)

Jan

1. Introduction

Is it possible to add explanation how an HTTP-API client might benefit
from understanding the specific reason 'out of credit'? To me, it is
not obvious that a client would do anything with this information
besides passing the written information on to the human or to a log
consumed by a human. In both cases 403+HTML would be sufficient.

I do not want to discuss the usefulness of the draft, but it would
be nice to have an example that isn't by any chance controversial.

Specifically, someone with my mindset could take this paragraph
as pure hand-waving:

  "However, that doesn't give the API client enough information about
   why the request was forbidden, the applicable account balance, or how
   to correct the problem.  If these details are included in the
   response body in a machine-readable format, the client can treat it
   appropriately."

Unless there is a bit more explanation what it could mean for a client
to treat "out of credit" appropriately or how to "correct the problem"
given understanding of the problem semantics.

IMHO, probem types are so very close to tunneling application semantics
that it is a good idea to be as clear as possible why HTTP status codes
are not enough. Otherwise I fear that readers just take it as a best
practice to solve with a zillion of problem types what could be solved by
good resource design. [I know we have been here already, but since this is
sort of last call, I say it again :-)]

3.2 Optional Members

"httpStatus" (number)  - Can you substitute "number" by the production for
HTTP status codes? E.g. IIS wrongly produces a hord of xxx.yy status
codes for finde grained, tunneled, error semantics. People might be tempted to
copy these as values for httpStatus.

"detail" (string) - I fail to understand how "detail", being a string, can help
a client do anything (expect display the string). Can you explain?

4.1. Example

The sentences

   "If one is available, you can reuse that URI by
   documenting use of both this specification and that specific URI
   value in your API."

and

   "This information could appear within the rest of your
   API's documentation"

contradict the idea that true HTTP APIs do not need documentation and
that such documentation creates expectations that get hard coded and
introduce coupling. It is a slippery slope to mention in a spec that
will likely receive widespread attention given its editor :-)

Jan

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 30 May 2013 10:23:36 +1000

Hi Jan,

> Excuse the 'purist mindset driven tone' - you know me, no offence intended :-)

Of course :)

> given understanding of the problem semantics.

Makes sense; I'll add some text.

> sort of last call, I say it again :-)]

If you have suggested text, I'm all ears; I tried to address this in the draft.

> copy these as values for httpStatus.

OK.

> a client do anything (expect display the string). Can you explain?

One use would be for an intermediary or other generic implementation when they're logging.

> will likely receive widespread attention given its editor :-)

Without getting into a debate about the One True HTTP API, they *do* need to document media types and link relations, at a minimum.

But I digress. I'll try to reword.

Thanks for the feedback!

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