Subject: [apps-discuss] WGLC on draft-ietf-appsawg-http-problem-00.txt

From: Alexey Melnikov <[email-masked]>
Date: Sun, 7 Dec 2014 22:44:10 +0000

This message starts 2 weeks WGLC on draft-ietf-appsawg-http-problem-00 (Problem Details for HTTP APIs). Please review and send your comments to the mailing list by December 21st, or state that the document is ready for publication.

Alexey,
as APPSAWG co-chair

---

From: Julian Reschke <[email-masked]>
Date: Mon, 08 Dec 2014 08:41:38 +0100

Hi,

below some feedback.

Not in the spec:

1) The spec doesn't mention that this sort of duplicates earlier work 
done in WebDAV; see 
<http://greenbytes.de/tech/webdav/rfc4918.html#precondition.postcondition.xml.elements>

2) The spec talks about using Accept to instruct the server whether to 
return problem details or HTML. Maybe it would be worthwhile to mention 
that if you use XML, you could *always* send problem details, and then 
use <http://www.w3.org/TR/xml-stylesheet/> to instruct the UA to convert 
to HTML; that would get rid of the conneg complexity.

In the spec:

 >    The data model for problem details is a JSON [RFC7159] object; when
 >    formatted as a JSON document, it uses the "application/problem+json"
 >    media type.  Appendix A defines how to express them in an equivalent
 >    XML format, which uses the "application/problem+xml" media type.

Why is this an appendix?

 >    A problem's type URI SHOULD resolve to HTML
 >    [W3C.REC-html401-19991224] documentation that explains how to resolve
 >    the problem.

Not sure why we need to mandate HTML here. If the ref is updated to 
HTML5 it would at least allow XHTML as well.

 >    If such additional members are defined, their names SHOULD start with
 >    a letter (ALPHA, as per [RFC5234]) and SHOULD consist of characters
 >    from ALPHA, DIGIT, and "_" (so that it can be serialized in formats
 >    other than JSON), and SHOULD be three characters or longer.

DIGIT should ref RFC5234 as well, optimally point readers directly to 
Appendix B.1.

 >    The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is:

What does "OPTIONAL" mean here? The schema doesn't seem optional at all; 
lacking it, you wouldn't even know what XML namespace to use.

 >    default namespace ns = "urn:ietf:rfc:XXXX"

This needs to state that it will be updated based on the assigned RFC 
number.

 >    start = problem
 >
 >    problem =
 >      element problem {
 >        (  element  type            { xsd:anyURI }?
 >         & element  title           { xsd:string }?
 >         & element  detail          { xsd:string }?
 >         & element  status          { xsd:positiveInteger }?
 >         & element  instance        { xsd:anyURI }? ),
 >        anyNsElement
 >      }
 >
 >    anyNsElement =
 >      (  element    ns:*  { anyNsElement | text }
 >       | attribute  *     { text })*
 >
 >    The media type for this format is "application/problem+xml".

 >    Extension arrays and objects can be serialized into the XML format by
 >    considering an element containing a child or children to represent an
 >    object, except for elements that contain only child element(s) named
 >    'i', which are considered arrays.  For example, an alternate version
 >    of the example above would appear in XML as:

This is written like guidance, but it's normative, right?

 >    HTTP/1.1 403 Forbidden
 >    Content-Type: application/problem+xml
 >    Content-Language: en
 >
 >    <?xml version="1.0" encoding="UTF-8"?>
 >    <problem xmlns="urn:ietf:rfc:XXXX">
 >      <type>http://example.com/probs/out-of-credit</type>
 >      <title>You do not have enough credit.</title>
 >      <detail>Your current balance is 30, but that costs 50.</detail>
 >      <instance>
 >        http://example.net/account/12345/msgs/abc
 >      </instance>

It would be good to point out that due to the type definitions in the 
schema, the whitespace inside <instance> is ignorable.

Editorial nits:

> 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.

s/invent/define/ maybe?

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

add "to be removed by RFC Editor..."

> 1. Introduction
>
>
>    HTTP [RFC7230] status codes are sometimes not sufficient to convey
>    enough information about an error to be helpful.  While humans behind
>    Web browsers can be informed about the nature of the problem with an
>    HTML [W3C.REC-html401-19991224] response body, non-human consumers of
>    so-called "HTTP APIs" are usually not.

You probably want to cite HTML5 now. Also, consider shortening the 
reference name to "HTML".

>    This specification defines simple JSON [RFC7159] and XML
>    [W3C.REC-xml-20081126] document formats to suit this purpose.  They
>    are designed to be reused by HTTP APIs, which can identify distinct
>    "problem types" specific to their needs.

...and to "XML".

>    Additionally, problems can contain other information, such as a URI
>    that identifies the specific occurrence of the problem (effectively
>    giving an identifier to the concept "The time Joe didn't have enough
>    credit last Thursday"), which may be useful for support or forensic
>    purposes.

s/may/can/

> 3.1. Problem Details Object Members
>
>
>    A problem details object MAY have the following members:

s/MAY have/can have/

>    o  "title" (string) - A short, human-readable summary of the problem
>       type.  It SHOULD NOT change from occurrence to occurrence of the
>       problem, except for purposes of localisation.

Does this imply localisation-per-request (Accept-Language?)

>    The detail member, if present, SHOULD focus on helping the client
>    correct the problem, rather than giving debugging information.

s/SHOULD/ought to/

>    Finally, an application may have a more appropriate way to carry an

s/may/might/

>    That said, it is possible to add support for problem details to
>    existing HTTP APIs using HTTP content negotiation (e.g., using the
>    Accept request header to indicate a preference for this format).

Reference Section 5.3.2 of RFC7231.

>    New problem type definitions MUST document:
>
>    1.  A type URI (typically, with the "http" scheme),
>
>    2.  A title that appropriately describes it (think short), and
>
>    3.  The HTTP status code for it to be used with.
>
>    Problem types MAY specify the use of the Retry-After response header
>    in appropriate circumstances.

s/Problem type/Problem type definitions/

Also reference Section 7.1.3 of RFC7231.

> 8.2. Informative References
>
>
>    [ISO-19757-2]
>               International Organization for Standardization,
>               "Information Technology --- Document Schema Definition
>               Languages (DSDL) --- Part 2: Grammar-based Validation ---
>               RELAX NG", ISO/IEC 19757-2, 2003.

This one sounds normative to me.

>    [W3C.REC-xml-20081126]
>               Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
>               F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
>               Edition)", World Wide Web Consortium Recommendation REC-
>               xml-20081126, November 2008,
>               <http://www.w3.org/TR/2008/REC-xml-20081126>.

Same here.

>    Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary
>    format convention.  Such APIs MAY express problem details using the
>    format defined in this appendix.

s/MAY/can/

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 9 Dec 2014 10:35:51 +1100

Guten Abend, Julian.

> On 8 Dec 2014, at 6:41 pm, Julian Reschke <[email-masked]> wrote:
> 
> Hi,
> 
> below some feedback.
> 
> Not in the spec:
> 
> 1) The spec doesn't mention that this sort of duplicates earlier work done in WebDAV; see <http://greenbytes.de/tech/webdav/rfc4918.html#precondition.postcondition.xml.elements>

If this were an academic paper, I think that'd be important. As a spec, I'm not sure that it is.

> 2) The spec talks about using Accept to instruct the server whether to return problem details or HTML. Maybe it would be worthwhile to mention that if you use XML, you could *always* send problem details, and then use <http://www.w3.org/TR/xml-stylesheet/> to instruct the UA to convert to HTML; that would get rid of the conneg complexity.

I'm not sure that browsers are going to support XSLT in the long run.

> >    XML format, which uses the "application/problem+xml" media type.

When all things are equal, I'd prefer people to use JSON for APIs, not XML. If we move it to be a peer of the JSON format, we'd need to have some text advising when to use each, and that could get sticky. Putting it in an appendix seemed like a reasonable compromise. If we don't put it in an appendix, I'd almost want to put it in a separate document...

> Not sure why we need to mandate HTML here. If the ref is updated to HTML5 it would at least allow XHTML as well.

Yes, the ref should be updated.

> DIGIT should ref RFC5234 as well, optimally point readers directly to Appendix B.1.

Ack.

> What does "OPTIONAL" mean here? The schema doesn't seem optional at all; lacking it, you wouldn't even know what XML namespace to use.

That's Erik's work, but I tend to agree.

> This needs to state that it will be updated based on the assigned RFC number.

Ack.

> It would be good to point out that due to the type definitions in the schema, the whitespace inside <instance> is ignorable.

I'll leave this to Erik...

> You probably want to cite HTML5 now. Also, consider shortening the reference name to "HTML".
> 

Thanks! Will incorporate.

Thanks again for the detailed and useful feedback.

Cheers,

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

---

From: Erik Wilde <[email-masked]>
Date: Mon, 08 Dec 2014 16:43:48 -0800

hello julian.

thanks for the detailed feedback!

> When all things are equal, I'd prefer people to use JSON for APIs, not XML. If we move it to be a peer of the JSON format, we'd need to have some text advising when to use each, and that could get…

to me, it seems like the error serialization should simply match the 
serialization of the rest of the API, so there wouldn't be a need to 
recommend anything beyond this.

as a side note, for home documents, we have the setup that mark is 
referring to: two separate documents for JSON and XML:

http://tools.ietf.org/html/draft-nottingham-json-home-03
http://tools.ietf.org/html/draft-wilde-home-xml-03

personally, i think it's easier to have one document explain the overall 
model, and then have two serializations of it in the same documents, but 
i am fine either way.

> That's Erik's work, but I tend to agree.

i have a hard time remembering why it says "OPTIONAL" here. i think the 
reason was that we did not want to recommend a specific schema language 
and were simply using RELAX NG as one possible choice. but i think 
you're right that the term "OPTIONAL" does not make a lot of sense.

>> This needs to state that it will be updated based on the assigned RFC number.

done. ("Note to RFC Editor: Please replace "XXXX" with assigned RFC 
number before publication.")

>> This is written like guidance, but it's normative, right?

good point. what about this wording instead:

Extension arrays and objects are serialized into the XML format by 
considering an element containing a child or children to represent an 
object, except for elements that contain only child element(s) named 
'i', which are considered arrays. For example, the XML version of the 

> I'll leave this to Erik...

actually, i think in this case it might be less confusing to simply not 
have this extraneous whitespace in the example, so my suggestion is to 
change example to simply say:

<instance>http://example.net/account/12345/msgs/abc</instance>

thanks again for the review! 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: Julian Reschke <[email-masked]>
Date: Tue, 09 Dec 2014 07:35:25 +0100

On 2014-12-09 01:43, Erik Wilde wrote:
>> Putting it in an appendix seemed like a reasonable compromise. If we
>> don't put it in an appendix, I'd almost want to put it in a separate
>> document...
>

Agreed.

> ...

Actually, this should request assignment of a "urn:ietf:params:xml:ns" 
URN, no?

> JSON example above would appear as:

Sounds good.

> thanks again for the review! cheers,

OK, so now we are avoiding the question about ignorable whitespace. So 
it's not ignorable, right?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 09 Dec 2014 08:26:04 +0100

> I'm not sure that browsers are going to support XSLT in the long run.

They do right now, and this can be used to avoid conneg altogether. Just 
saying.

> When all things are equal, I'd prefer people to use JSON for APIs, not XML. If we move it to be a peer of the JSON format, we'd need to have some text advising when to use each, and that could get…

I disagree that we need to advise which to use.

Best regards, Julian

---

From: Erik Wilde <[email-masked]>
Date: Tue, 09 Dec 2014 09:22:03 -0800

hello julian.

> Actually, this should request assignment of a "urn:ietf:params:xml:ns"

not necessarily, no. all we need is a unique URI to identify the 
namespace for HTTP problems in XML. the simpler urn:ietf:rfc:XXXX form 
is sufficient here, and there is no registration requirement for those 
URIs (RFC 2648 defines this IETF URN namespace).

> it's not ignorable, right?

i would want to avoid any processing model that depends on knowing and 
using the/a schema. that's usually a problem, because many 
implementations will simply operate on the XML parse tree and not apply 
any kind of schema validation/processing.

i think i am not quite sure what you would want to see here. the value 
contained in the XML element "means" the same as a value contained in 
the corresponding JSON serialization; any difference between them means 
that the serialized HTTP problem object has those differences as well.

thanks and cheers,

dret.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 09 Dec 2014 18:29:10 +0100

> URIs (RFC 2648 defines this IETF URN namespace).

Hmmm. I think it'll cause confusion. I also think that not having the 
rfc# in it will be better in case we'll ever revise this document.

> any kind of schema validation/processing.

+1

> that the serialized HTTP problem object has those differences as well.

OK, so then let's agree that the example was misleading :-)

Best regards, Julian

---

From: Erik Wilde <[email-masked]>
Date: Tue, 09 Dec 2014 11:54:03 -0800

hello julian.

> rfc# in it will be better in case we'll ever revise this document.

i am pretty sure it works either way. it's as simple as it gets for a 
URI that clearly identifies an RFC. and as long as the "XML schema" 
stays the same, it should be identified by the same URI, and when it 
gets changed in a possible future update of the spec, then the URI 
should change anyway to identify the new schema.

> OK, so then let's agree that the example was misleading :-)

thanks for spotting it!

cheers,

dret.

---

From: Cyrus Daboo <[email-masked]>
Date: Mon, 15 Dec 2014 14:38:01 -0500

Hi Alexey,

--On December 7, 2014 at 10:44:10 PM +0000 Alexey Melnikov 
<[email-masked]> wrote:

> This message starts 2 weeks WGLC on draft-ietf-appsawg-http-problem-00
> (Problem Details for HTTP APIs). Please review and send your comments to
> the mailing list by December 21st, or state that the document is ready
> for publication.

I support publication of this draft. A draft I am working on already 
references it 
(<https://datatracker.ietf.org/doc/draft-ietf-tzdist-service/>).

One comment: the definition of the "type" member in Section 3.1 and the 
text in Section 4 both recommend that the "type" resolve to HTML 
documentation. In tzdist we have a "urn:ietf:params:tzdist:error:" 
sub-namespace for error codes that the protocol itself defines and that we 
use for the "type" URI value. I think it may be fairly common for protocols 
creating new HTTP apis to do something similar, so I wonder if that should 
be called out as a "recommended" solution too?

-- 
Cyrus Daboo

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 27 Dec 2014 09:31:29 -0500

> On 15 Dec 2014, at 2:38 pm, Cyrus Daboo <[email-masked]> wrote:
> 
> One comment: the definition of the "type" member in Section 3.1 and the text in Section 4 both recommend that the "type" resolve to HTML documentation. In tzdist we have a "urn:ietf:params:tzdist:error:" sub-namespace for error codes that the protocol itself defines and that we use for the "type" URI value. I think it may be fairly common for protocols creating new HTTP apis to do something similar, so I wonder if that should be called out as a "recommended" solution too?

I don’t know if I’d go as far as to recommend that as a practice; most users of this draft will not be creating IETF protocols, I think. 

That said, I’m happy to add more context here to make it clear that it’s a general recommendation, with exceptions such as the one you mention.

Cheers,

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