Re: [spec-reviews] http-problem (#37)

Thanks for the review. A few responses:

> Here's what I got. Should I deliver it to apps-discuss, or pull request it here, or should we workshop it first, or...?

I'll send a link to this to apps-discuss for their info.

> A proposal along these lines is sorely needed on the web, as explained very well by its introduction. My main concerns are around the confusing nature of type, title, and message fields, and how they might not be suited for common use cases.

Great!
 
> My first concern is the recommendation that "type" be a dereferenceable URL. I think many APIs will simply want to have a unique-within-their-API ID per problem type, but that seems to be implicitly discouraged by this document, which wants them to mint new HTTP-accessible HTML pages describing the problem. I understand how it's very nice to have this kind of self-describing type, similar to link relations. But I worry that the additional burden will discourage people from using this format, or will end up with them putting non-URLs in the type field.

Well, it's a SHOULD, so you can violate it if you have reason to. It's a requirement because it seemed important to document the error type, but I agree that it might be too high a bar -- it's more of a strong suggestion than a requirement.

I'm happy to downgrade it to something more suggestive.

BTW, just to be clear, you're not saying it's a problem that it's a URI (possibly relative), correct?
 
> I'm also unsure how to make sense of the combination of "title" plus "detail". Given that both are meant to be human-readable, when is the separation helpful?

"title" is defined by the error type, and therefore static between instances of the error. "detail" is specific to a particular instance.

> What is the recommended way to display this to humans: title, two newlines, then detail, perhaps?

SGTM.

> Most error-communication systems in programming langauges have a machine-readable type (e.g. TypeError, IOError, etc.) and a single human-readable string (often message). I would venture a guess that many developers model their conception of errors similarly. Introducing two human-readable fields makes it harder to conceptualize how this is supposed to map to existing systems, or how to display the resulting error to the user. Ideally, I think, there would be a single "message" field, which could be mapped to that same field in most programming languages.

I think the mapping is:

* "type" - error type
* "title" - human readable description of error type
* "detail" - stack trace (except we don't want actual stack traces exposed via HTTP APIs, usually, because that's a security issue)
 
> The "instance" field seems to be of unclear utility. In which scenario would this be useful? Is it worth making it part of the spec, instead of letting it be a per-scenario extension? How do you envision it being generically processed?

For example, you might use it to correlate a particular instance of an error in logs, identify it in support calls, etc.

Make sense, or need more convincing?

> The optional "status" field seems fragile, as mentioned in section 5. What is the purpose of including it, especially since it is optional?

Many people complain that the HTTP status code isn't available in their API, or isn't persisted in their systems, so putting it in the body preserves that information. Personally, I'm ambivalent about this, and happy to drop it; they can infer the intended status from the type's documentation.

> Finally, I'm unsure how comfortable I am with the lack of constraints on extension members. It might be more future-proof, or perhaps just cleaner, to separate them into a sub-object ({ "type": ..., "title": ..., "other": { "customer_id": ... } } or similar). Or, simply mandate that they must begin with a given prefix (an underscore, "other_", "details-", ...).

I like the sound of that. Any preference in terms of style?

> All in all though, this is really exciting. If it takes off, you could imagine it having ripple effects across web architecture. For just one example, you could imagine a built-in option to fetch that will use a application/problem+json response to construct a JavaScript Error object with its fields appropriately pre-filled, and reject the resulting promise instead of relying on a status-code-then-parse-error path in the fulfillment handler. Or, if the URL-based error identifier approach really takes off, you could imagine it helping solve our problem in JavaScript of identifying errors more precisely.

In-ter-esting!

---
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/spec-reviews/issues/37#issuecomment-85134293