Re: [httpapi] Discussion of adopting Content-Warning header

[André Cedik <[e-mail]>]

Thank you for the reply Mark.
Let me take a step back and explain where I'm coming from. Maybe this can
clear up things.

For those who don't know shipcloud.io we're a so-called shipping service
provider. So just like e.g. Stripe who's connecting you to payment
providers, we're aggregating the (web) services of shipping providers
(carriers) like UPS, FedEx, etc. into a single API and are making them
available via a SaaS business model.

Since every carrier is handling things "a little bit" differently it's not
always so easy to communicate certain things back to our (API) users.
Especially when it comes to what I would call "outcomes of internal
automation/knowledge". One of those examples would be the automatic
correction of addresses. To create a shipping label at a carrier, we of
course have to send them the recipients' and senders' addresses. Based on
their services' knowledge of address data, they may change an address to
something that they know is (more) correct. This is done on their side and
when the return gets back to us, we are also getting the information that
they've changed something while processing our request. So now we basically
receive a set of data that doesn't match the original request.

To be able to convey to (API) users that something has changed and they
should have a look at it before just accepting the fact,  is my main goal
because they will be charged for the shipping label that has been created
nonetheless.

What I would like to achieve is something that Erik already was able to do
by introducing application/problem+json with RFC 7808, creating a standard
people can use without having to reinvent the wheel. This would make API
adoption easier because consumers of an API wouldn't have to figure out how
warnings are transported for a specific API.

The challenge with warnings from my point of view is the fact that the
original request was successful - in our case, a shipping label has been
created - but there were "side effects" that may need to be addressed. If
it would only boil down to this I'd say "let's create a
content-type application/warnings+json" or something similar. But I would
make the assumption that there are use cases where warnings and errors can
both happen with one request. Maybe because something happened at an
intermediary and the destination server which is processing the request is
throwing e.g. a server error. This is one of the reasons why we opted to
make it a header field. The other being that there might be other use cases
where an "embedded-warning" doesn't make sense. This is why the concept of
a registry was introduced to create other warning types.

I'm sure there are other use cases similar or exactly like ours since the
feedback we received so far has been positive towards creating a standard
for warning information.

Just let me know if I was able to clear things up a bit, or if you need
more information.

On Thu, Jan 28, 2021 at 7:39 AM Mark Nottingham <[e-mail]> wrote:

> Hi,
>
> I've re-read this draft.
>
> I don't understand what the use case is -- specifically, what benefit
> exposing this information in a header field brings.
>
> The JSON format described can already be used, and is identified with a
> distinct media type; that should be enough to indicate to a recipient that
> the content of the message is a problem.
>
> Are there cases where it's expected that generic HTTP software (e.g., an
> intermediary) separate from the application in question is going to need to
> know this information? That's the usual reason for standardising a header
> field (the other being that the format doesn't accommodate that information
> in question, but that doesn't seem to be the case here).
>
> Cheers,
>
>
> > On 11 Dec 2020, at 3:07 am, Salz, Rich <rsalz=
> [e-mail]> wrote:
> >
> > At our meeting at IETF 109, we discussed
> >
> https://tools.ietf.org/html/draft-cedik-http-warning-02
> >
> > Let’s discuss this (we didn’t have enough time at the virtual). Feel
> free to use this thread or start new ones.
> > --
> > httpapi mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/httpapi
>
> --
> Mark Nottingham   https://www.mnot.net/
>
> --
> httpapi mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/httpapi
>