Problem Details for HTTP APIs
draft-ietf-appsawg-http-problem-03

[Ballot discuss]
I'm elevating this to a (late) Discuss, because I haven't heard anything back, and didn't want the document approved without having a (short) discussion. I'll be back to Yes after that.

In this text,

  The "status" member duplicates the information available in the HTTP
  status code itself, thereby bringing the possibility of disagreement
  between the two.  Their relative precedence is not clear, since a
  disagreement might indicate that (for example) an intermediary has
  modified the HTTP status code in transit.  As such, those defining
  problem types as well as generators and consumers of problems need to
  be aware that generic software (such as proxies, load balancers,
  firewalls, virus scanners) are unlikely to know of or respect the
  status code conveyed in this member.
 
I understand what you're saying about a mismatch being possible, and some of the possible reasons why that might happen, but isn't this saying that anyone who can understand the "status" member should prefer its value when there's a mismatch (because it's less likely to have been dorked with by an intermediary - or is that even true)?

So, the situation looks to me, like there's a MUST

  The status member, if present, is only advisory; it conveys the HTTP
  status code used for the convenience of the consumer.  Generators
  MUST use the same status code in the actual HTTP response, to assure
  that generic HTTP software that does not understand this format still
  behaves correctly. 

that some intermediary can dork with, so the result violates the MUST, and we really can't tell the receiver what you should do at that point. "Gee, I guess you're gonna have to flip a coin to decide who to believe" would be sad, but it would be more guidance than the document has now :-)

[Ballot comment]
I've wished this mechanism was available, a few times already.

In this text,

  If such additional members are defined, their names SHOULD start with
  a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist
  of characters from ALPHA, DIGIT (Ibid.), and "_" (so that it can be
  serialized in formats other than JSON), and SHOULD be three
  characters or longer.
 
are there any benefits to not conforming to these SHOULDs? For example, would you really need to have a two-character member name, and you'd fail if the member name was three characters long? ("Why are these not MUSTs?")

[Ballot comment]
Section 4 talks about how a problem type SHOULD resolve to HTML documentation. Is there ever a case where an API might be standardized to be used by multiple origin servers? Would each server host it's own documentation? Would the problem type be a relative URL under those circumstances? (You say it can be relative, but all the examples are fully qualified)

- 4, 2nd paragraph: "New problem types need to carefully
  consider..."
This is a pedantic nit, really a personal pet peeve: Designers of new problem types should consider this. I doubt the types themselves will :-)

[Ballot comment]
I've wished this mechanism was available, a few times already.

In this text,

  If such additional members are defined, their names SHOULD start with
  a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist
  of characters from ALPHA, DIGIT (Ibid.), and "_" (so that it can be
  serialized in formats other than JSON), and SHOULD be three
  characters or longer.
 
are there any benefits to not conforming to these SHOULDs? For example, would you really need to have a two-character member name, and you'd fail if the member name was three characters long? ("Why are these not MUSTs?")

In this text,

  The "status" member duplicates the information available in the HTTP
  status code itself, thereby bringing the possibility of disagreement
  between the two.  Their relative precedence is not clear, since a
  disagreement might indicate that (for example) an intermediary has
  modified the HTTP status code in transit.  As such, those defining
  problem types as well as generators and consumers of problems need to
  be aware that generic software (such as proxies, load balancers,
  firewalls, virus scanners) are unlikely to know of or respect the
  status code conveyed in this member.
 
I understand what you're saying about a mismatch being possible, and some of the possible reasons why that might happen, but isn't this saying that anyone who can understand the "status" member should prefer its value when there's a mismatch (because it's less likely to have been dorked with by an intermediary - or is that even true)?

[Ballot comment]

- 3.1: "SHOULD NOT automatically" de-ref the type URI. Hmm, under
what circumstances would it be reasonable for any code to
automatically de-ref the type URI? If none, then either
s/SHOULD/MUST/ or maybe s/automatically//

- 3.1, last para: I'm sure this is a known thing, but I don't know
the answer, so I'll ask:-) If I send a request for URL
example.com/foo and am re-directed to example.net/bar, against which
of those is a relative URL in the problem detail evaluated?  I hope
the answer is example.net - if not, there could be some attack that
could be mounted but I've not got a concrete example to offer.

- 3.2, last para: should "media type" be "problem type" at the end?

- 4: "typically with the "http" scheme" - your examples are all
https, don't you mean https here too?

(Via drafts-lastcall-comment@iana.org): IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-appsawg-http-problem-01.txt. If any part of this review is inaccurate, please let us know.

IANA understands that, upon approval of this document, there is a single action which IANA must complete.

In the application media types registry located at:

http://www.iana.org/assignments/media-types/

two new media types are to be added as follows:

Name: problem+json
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Name: problem+xml
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

IANA understands that this is the only action required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is only to confirm what actions will be performed. 

Thank you,

Sabrina Tanamal
IANA Specialist
ICANN

The following Last Call announcement was sent out:

From: The IESG
To: "IETF-Announce"
CC: appsawg-chairs@ietf.org, apps-discuss@ietf.org, "Murray Kucherawy" , superuser@gmail.com, barryleiba@gmail.com, draft-ietf-appsawg-http-problem@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Problem Details for HTTP APIs) to Proposed Standard


The IESG has received a request from the ART Area General Applications
Working Group WG (appsawg) to consider the following document:
- 'Problem Details for HTTP APIs'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2015-12-04. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This document defines a "problem detail" as a way to carry machine-
  readable details of errors in a HTTP response, to avoid the need to
  invent new error response formats for HTTP APIs.

Note to Readers

  This draft should be discussed on the apps-discuss mailing list [1].




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-appsawg-http-problem/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-appsawg-http-problem/ballot/


No IPR declarations have been submitted directly on this I-D.

Murray Kucherawy is the document shepherd.  Barry Leiba is the
responsible Area Director.

This document defines a "problem detail" as a way to carry machine-
readable details of errors in a HTTP response, to avoid the need to
invent new error response formats for HTTP APIs.

The working group requests Proposed Standard status, as it qualifies for
such per RFC 2026 Section 4.1.1.  In particular, the proposal is thought
to be useful enough that there are several implementations (see
https://github.com/mnot/I-D/wiki/http-problem), it has review from both
the HTTP community at the IETF and the W3C (the TAG), and its
advancement has the support of APPSAWG.

WGLC finished almost a year ago, and there has been a small amount of
activity since then which has been incorporated into the document.  Much
of the delay since then has been caused by waiting for TAG feedback
(which never came), and the remainder of the blame falls on the WG
chairs.  It's ready for formal processing.

2. Review and Consensus

The document originally appeared as an individual submission in July of
2012 and went through some evolution resulting in several revisions
before being adopted by APPSAWG about a year ago.  It has been largely
stable since then.  There has been cross-development between APPSAWG
participants and W3C TAG.  Development has stabilized since its WGLC,
and implementations have matured with little change to the document.

Perhaps noteworthy with respect to consensus is that the participants of
APPSAWG cover a broad area of applications, and only some focus on HTTP
work.  However, that smaller group does tend to be active and thorough
when they take up a work item in their specific interest area.  With
that in mind, consensus on the current content appears to be solid
rather than rough.

One of the document authors is both HTTPBIS chair and also the IETF
liaison to the W3C, so I'm satisfied that there has been ample airing of
this proposal on both sides of that particular fence.

3. Intellectual Property

Both authors have affirmed that they have already disclosed all direct,
personal knowledge of any IPR related to this document, in conformance
with BCPs 78 and 79.

4. Other Points

IANA Considerations appears to be properly formed.  To the eyes of this
media type reviewer-in-training, the registrations appear to be sound,
especially in the areas for which we usually send registrations back to
the authors.

There are no downward normative references.

Nothing else of note.

Murray Kucherawy is the document shepherd.  Barry Leiba is the responsible Area Director.

  This document defines a "problem detail" as a way to carry machine-
  readable details of errors in a HTTP response, to avoid the need to
  invent new error response formats for HTTP APIs.

The working group requests Proposed Standard status, as it qualifies for such per RFC 2026 Section 4.1.1.  In particular, the proposal is thought to be useful enough that there are several implementations (see https://github.com/mnot/I-D/wiki/http-problem), it has review from both the HTTP community at the IETF and the W3C (the TAG), and its advancement has the support of APPSAWG.

WGLC finished almost a year ago, and there has been a small amount of activity since then which has been incorporated into the document.  Much of the delay since then has been caused by waiting for TAG feedback (which never came), and the remainder of the blame falls on the WG chairs.  It's ready for formal processing.

2. Review and Consensus

The document originally appeared as an individual submission in July of 2012 and went through some evolution resulting in several revisions before being adopted by APPSAWG about a year ago.  It has been largely stable since then.  There has been cross-development between APPSAWG participants and W3C TAG.  Development has stabilized since its WGLC, and implementations have matured with little change to the document.

Perhaps noteworthy with respect to consensus is that the participants of APPSAWG cover a broad area of applications, and only some focus on HTTP work.  However, that smaller group does tend to be active and thorough when they take up a work item in their specific interest area.  With that in mind, consensus on the current content appears to be solid rather than rough.

One of the document authors is both HTTPBIS chair and also the IETF liaison to the W3C, so I'm satisfied that there has been ample airing of this proposal on both sides of that particular fence.

3. Intellectual Property

Both authors have affirmed that they have already disclosed all direct, personal knowledge of any IPR related to this document, in conformance with BCPs 78 and 79.

4. Other Points

IANA Considerations appears to be properly formed.  To the eyes of this media type reviewer-in-training, the registrations appear to be sound, especially in the areas for which we usually send registrations back to the authors.

There are no downward normative references.

Nothing else of note.