Re: Communicating Warning Information in HTTP APIs

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

It is our goal to provide an easy way for API consumers to react to the
fact, that something has happened which they could/should act upon.

Since HTTP response status codes do not provide a category / a single code
for telling the client that there are warnings, our best bet was / is to
use the warning header to actually warn the api consumer and make it easy
for them act.

For the API consumer it should be just as easy to check whether the
response has an HTTP status code of 200 (when successful) or > 400 (when an
error occurred) as it should be to find out that something has happened (in
the backend), that caused a warning.

When providing only the JSON structure in the body, an API consumer would
always have to parse the body to get the "warnings"-entry and see if it is
filled with content.

When also providing a header, the consumer wouldn't necessarily have to
parse the body which would remove the need to parse large response bodies
(depending on the use case).

I can also imagine that API providers would like to provide the option to
send a request via the HTTP HEAD method to make it possible for consumers
to see if their request would be rejected, returns warnings or is
successful, when doing the actual POST request.