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

From: André Cedik <[email-masked]>
Date: Mon, 11 Jan 2021 13:21:36 +0100

Hey everyone and a happy new year,

I'd like to take the opportunity (since it is the first day back at work
for me) to get the ball rolling again.

Interestingly my first message in December seems to not have made it to the
list. At least that's what I get from the archive, where it is missing.
So I've added it to the end just for reference since the discussion has
already been going further.

Back to Darrel's question/suggestion.

I have certainly run into scenarios where there is value in returning
> warnings with a response and I've see the Warnings header from RFC 7234
> used in several cases.  However, the Warning header includes the Warn-Code
> to provide some details about the reason for the warning.  One advantage of
> using the Warning header was the fact that the warnings did not need to
> affect the structure of the payload.
> Would you consider a change to this draft that enabled representing
> details of the warning in the header itself?

Do you already have anything specific in mind? Maybe even an example when
warnings were returned using the Warnings header?
It would definitely make sense to have some kind of "code" to be returned
when a warning is present, but I am not sure if the use cases for different
APIs might be too specific to be handled by an overarching code. Hence
every API might need different codes for what they are trying to convey.
The advantage of returning the warnings in the body would be that more
specific information could be returned than trying to squeeze it into the
header.

Roberto is right. It would be possible to add more specific things using
the Content-Warning Type Registry

---

Original message:

> Thank you Rich for bringing this up again.
> I was planning on writing to the list about the draft, but haven't found
> the time yet. So it's great that you put some pressure on us.
> Let me try to answer two of the questions that came up during the IETF 109
> meeting.
>

Is this just for JSON documents?
> Absolutely not!
> It is the goal of the header to signal to a client that warnings are
> being returned.
> The value "embedded-warning" is merely one idea of telling this client,
> that more information can be found in the body.
> One could return a different content type than "application/json" and
> embed the warnings in there.
> The example shown in section 6 (
> https://tools.ietf.org/html/draft-cedik-http-warning-02#section-6) is
> just there so we have a proposition of how this could be returned.
> Ideally, we'd have a common way of returning warnings. Independent of what
> the content type is. But I'm not sure if this is possible.
>

Can we mix errors and warnings?
> If you have a look at the initial proposal - which was based on the
> warning header - we've had an example with errors and warnings.
> https://tools.ietf.org/html/draft-cedik-http-warning-00#section-5.2
> I can definitely see that there is a use case for having both at the same
> time since a warning could have occurred before the actual error came to
> be. So in this case returning the warning and the error could be helpful
> for a client.
> If you have further questions just let me know.

Best
André

On Tue, Dec 15, 2020 at 4:32 PM Roberto Polli <[email-masked]> wrote:

> Hi @all,
>
>
> Il giorno mar 15 dic 2020 alle ore 06:00 Darrel Miller
> <Darrel.Miller=[email-masked]> ha scritto:
> > > if
> > > there isn't enough interest, an alternative path may be to keep
> > > developing it as an individual draft
> I think this draft will benefit from a wider discussion, including the
> considerations provided by Darrell.
>
> > [..] I've see the Warnings header from RFC 7234 used in several cases.
> > [..] One advantage of using the Warning header was the fact that the
> warnings did not need to affect the structure of the payload.
> > Would you consider a change to this draft that enabled representing
> details of the warning in the header itself?
> iiuc this behavior can be configured via the content-warning-type: the
> payload one is  "embedded-warning",
> so the field definition already has an extension mechanism capable of
> supporting further types, eg "expensive-request" or "old-api-version"
> or whatever.
>
> I think this kind of discussions are the kind of activity of the workgroup.
>
> Have a nice day,
> R.
>
> --
> httpapi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/httpapi
>

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Jan 2021 17:38:58 +1100

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=[email-masked]> 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
> [email-masked]

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

---

From: André Cedik <[email-masked]>
Date: Thu, 28 Jan 2021 09:21:42 +0100

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 <[email-masked]> 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,
>
>
> > 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
> > [email-masked]

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Jan 2021 19:28:53 +1100

Hi André,

> On 28 Jan 2021, at 7:21 pm, André Cedik <[email-masked]> wrote:
> 
> 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 not sure that assumption holds. There may indeed be other use cases for warnings in APIs that justify a header, but without seeing them, it's hard to tell if the design you've proposed will address them. Your use case can be addressed by using RFC7807, so why not just use that?

Cheers,

---

From: Roberto Polli <[email-masked]>
Date: Thu, 28 Jan 2021 09:49:58 +0100

Hi @all,

Il giorno gio 28 gen 2021 alle ore 09:29 Mark Nottingham
<[email-masked]> ha scritto:
> There may indeed be other use cases for warnings in APIs that justify a header, but without seeing them, it's hard to tell if the design you've proposed will address them.

imho there is a general interest in a replacement of the `Warning`
header (eg. to set alerts in payload-agnostic monitoring systems).
I agree that a strong relationship with the payload data raises
various issues, including Mark's ones.

My suggestion to André - that may still not address Mark's concerns - is to:
1- dis-entangle his proposal from the `Content` (eg. `Api-Warning`)
2- retain the "warning-type" registry, which can specify the type of
warning including content-warning

my 2¢,
R.

-- 
Roberto Polli
API Expert
M. +39 3406522736
MID
DIPARTIMENTO PER LA
TRASFORMAZIONE
DIGITALE
Presidenza del Consiglio dei Ministri - Ministro per l'innovazione
tecnologica e la digitalizzazione
https://innovazione.gov.it/

Il Dipartimento per la Trasformazione Digitale, salvo eccezioni,
comunica con le altre Amministrazioni via posta elettronica ordinaria
e non posta elettronica certificata, in conformità a quanto previsto
dall’art.47 del Codice dell’Amministrazione Digitale.

---

From: Asbjørn Ulsberg <[email-masked]>
Date: Thu, 28 Jan 2021 10:35:16 +0100

> header (eg. to set alerts in payload-agnostic monitoring systems).

I also envision the utility of intermediaries adding Content-Warning
to indicate trouble understanding the request or response in one way
or another, which may lead to a much better developer experience when
these intermediaries are added to a request or response pipeline.

> 1- dis-entangle his proposal from the `Content` (eg. `Api-Warning`)

+1. I think "Warning" is a good name, but think it has greater utility
in being general and content type agnostic. Think about a reverse
proxy being configured to perform CSS minification, for instance; if
it fails parsing the CSS, it can leave the CSS untouched but add a
Warning in the response regarding the syntax error it encountered.

> warning including content-warning

On first skimming of the draft, I actually thought the "type" was
equal to "type" in RFC 7807, i.e. a URI. I was both surprised and a
bit disappointed to learn that was not the case.

I think having a registry for different warning types adds needless
friction and bureaucracy, without providing much benefit. Using a URI
like in RFC 7807 allows the same types already minted for problem+json
to be reused, allows for distributed and friction-free creation of
types and makes it possible for type URIs to be dereferenced directly
in order to read more about why the warning occurred and how it can be
remedied.

-- 
Asbjørn Ulsberg           -=|=-        [email-masked]
«He's a loathsome offensive brute, yet I can't look away»