[httpapi] RFC for HTTP API error responses (was: rfc7807 errata or just "more")

[Ben Bucksch <[e-mail]>]

Hello Sanjay, hello everybody,

thank you for bringing this up. In fact, this topic is the very reason 
why I joined this mailling list and WG: I find that error responses - 
and more generally error handling - is severely lacking in many systems 
I come across, and it's causing problems during software development.

I wanted to propose to make a new RFC for nailling down not only the 
error responses, but also what information is expected in the response, 
and the behavioral contract. Errors should be part of the protocol and 
API contract.

I had written some document for my project and teams, in my role as 
software architect, based on my experience, and I wanted to share that 
with you as starting point for an RFC. The document I have is not 
suitable as Standard document, it's an software architecture document, 
but I think many of the ideas are viable to be included in the RFC.

I would like to ask you, esp. the leaders of the WG: Would you be 
willing to discuss and adopt such a new RFC? It would probably include 
RFC 7807, but significantly extend it in its scope.

Ben Bucksch


Am 15.01.21 um 19:32 schrieb Sanjay Dalal:
> Hello all,
>
> Thanks folks for providing instructions on how to provide feedback to 
> an RFC. This feedback is for RFC 7807 
> <https://tools.ietf.org/html/rfc7807>, "Problem Details for HTTP APIs".
>
> I like RFC 7807. In fact, I have designed Error Catalog Service 
> <https://github.com/sdatspun2/error-catalog-service> such that the 
> problem types of RFC 7807 can be managed (CRUDL) and used in error 
> responses, API definition, API documentation, API testing, etc.
>
> However, I find that RFC 7807 omitted one very common use case in its 
> proposed schema for Problem Details Object 
> <https://tools.ietf.org/html/rfc7807#section-3.1> (section 3.1). This 
> use case is about reporting of multiple errors of the same problem 
> type in an error response. RFC suggests defining an extension for this 
> use case.
>
> As you know, having multiple schema validation related errors in 
> payload of HTTP requests is a very common scenario for the HTTP APIs. 
> How can we improve the Problem Details Object schema to accommodate 
> this common use case? We should not expect API developers to respond 
> with one error at a time in the case of 400 scenarios. That would be 
> an unpleasant developer experience. Asking the API developers to 
> define an extension for such a common scenario hurts in adoption of 
> the Problem Types.
>
> In my opinion, instead of the proposed singular "*instance*" property 
> of type string, there should be an array of *instances. *You can find 
> what we have done for the error response of the Error Catalog service 
> <https://github.com/sdatspun2/error-catalog-service/blob/master/ErrorResponseInErrorCatalog.md>.There 
> could be other ways.
> *
> *
> I have communicated with both Erik Wilde and Mark Nottingham about 
> this issue. Both of them are open to discussing a revision under this 
> WG if the group thinks it is necessary. Would love to get your 
> comments, opinions, approaches and suggestions.
>
> thanks and regards,
> sanjay
>
>
> >    I am not too familiar with the process to comment an RFC but is 
> there in general
>     a form where I can provide written feedback to existing 
> specifications or is
>     this done through this mailing list?
>
> >On Sat, Jan 9, 2021 at 9:40 AM Salz, Rich 
> <rsalz=[e-mail] 
> <mailto:[e-mail]>> wrote:
> RFC's are published documents, not drafts; the name "request for 
> comments" is a node to IETF history.  How to provide feedback on 
> published RFC's depends on the amount and nature of feedback. If you 
> have a well-contained technical error, you want to report an "errata" 
> against the RFC.  If it's more philosophical or just "more", it might 
> be better to find the WG that published the RFC and post to that 
> mailing list (see above).
>