Subject: Re: Communicating Warning Information in HTTP APIs

From: André Cedik <[email-masked]>
Date: Tue, 19 Nov 2019 06:10:15 +0100

Sorry for getting back to you so late. I was sick for more than a week and
had no chance to answer at all.

First of all thank you for the Feedback Mark.

I'm a little conflicted as to where we should discuss this further. Since
Roy recently answered to this issue (https://github.com/dret/I-D/issues/125),
the discussion over there is moving a little faster.

Nonetheless, I would love to tell you the use case(es) from which the
original idea for the I-D was born. The company I'm working for is a
shipping service provider. This means that we've integrated shipping
carriers like UPS, DHL, TNT, etc. into a single platform and are providing
them via our own api to our customers.

One of the most basic things you can do with the api is creating a shipping
label for sending a parcel from point a to point b. You can either use one
of the carrier contracts we provide to buy the shipping label or you can
use your own account with a carrier. This means that either we charge our
customer for the label or the carrier does this directly.

Unfortunately there are cases, where the service of a shipping carrier
creates a shipping label and therefore charges (either us or the customer)
for their service, but in the backend not everything went perfect. Let me
clarify this:

   - we send the data to the web service of the carrier
   - the carrier creates the shipping label and returns it to us
   - since not all data was 100% correct, the carrier also returns
   annotations, that they've done something (to the request) to "make it work"

The thing is we need to inform the customer of this automatic behaviour
that is out of our hand, since they can get charged extra for what the
carrier has done in the background.

I'm hoping that I was able to shed a bit of light into what at least our
use case is. We're currently on the lookout for more use cases which I'm
sure are out there, to get a better understanding about we can create a
generalized approach to communicating errors in http apis.

All the best
André

---

From: Asanka Herath <[email-masked]>
Date: Tue, 19 Nov 2019 12:07:13 -0500

Is there a use case where the Warning header is required to be a HTTP
header instead of being encoded into the body?

As proposed it seems the Warning header could ossify into a generic
metadata channel that is of no utility to a generic UA.

On Tue, Nov 19, 2019 at 12:13 AM André Cedik <[email-masked]>
wrote:

> Roy recently answered to this issue (
> https://github.com/dret/I-D/issues/125), the discussion over there is
> moving a little faster.
>
> One of the most basic things you can do with the api is creating a
> shipping label for sending a parcel from point a to point b. You can either
> use one of the carrier contracts we provide to buy the shipping label or
> you can use your own account with a carrier. This means that either we
> charge our customer for the label or the carrier does this directly.
>

---

From: [email-masked]
Date: Wed, 20 Nov 2019 10:38:32 -0500

I have wanted Warning headers on a few occasions, sometimes for metadata that doesn't make sense inside a resource representation (e.g., use of a deprecated media type or some aspect of the request being ignored, such as an unknown URL query parameter or specification of a protected field in the payload) and sometimes for communicating with a client independent of any particular resource altogether (e.g., approaching a rate limit or session expiration).

There were also more use cases in the past, but I feel that improvements such as Preference and Preference-Applied have satisfactorily addressed them.