Re: Communicating Warning Information in HTTP APIs

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é