Communicating Warning Information in HTTP APIsshipcloud GmbHandre.cedik@googlemail.comAxwayerik.wilde@dret.nethttp://dret.net/netdret/
This document defines a warning code and a standard response format for warning information in HTTP APIs.
This draft should be discussed on the rfc-interest mailing list ().Online access to all versions and files is available on GitHub ().
Many current APIs are based on HTTP
as their application protocol. Their
response handling model is based on the assumption that requests either are
successful or they fail. In both cases (success and fail) an HTTP status code
is returned to convey either fact.
But response status is not always strictly either success or failure. For example, there are cases where an underlying
system returns a response with data that cannot be defined as a clear error. API
providers who are integrating such a service might want to
return a correct response nonetheless, but returning a HTTP status code of e.g. 200 OK
without any additional information is not the only possible approach in this case.
As defined in the principles of Web architecture
, agents that "recover from errors by
making a choice without the user's consent are not acting on the user's behalf".
Therefore APIs should be able to communicate what has happened to their consumers, which then allows clients or users to make more informed decisions.
This document defines a warning code and a standard response structure for communicating and representing warning
information in HTTP APIs. The goal is to allow HTTP providers to have a standardized way of communicating to their consumers that while the response can be considered to be a non-failure, there is some warning information available that they might want to take into account.
As a general guideline, warning information should be considered to be any information that can be safely ignored (treating the response as if it did not contain any warning information), but that might help clients and users to make better decisions.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
described in .
As described in section 5.5 of the Warning header field "is
used to carry additional information about the status or transformation of a message
that might not be reflected in the status code". The field itself consists of the
warn-code, a warn-agent, a warn-text, and an optional warn-date.
As mentioned in the introduction (), HTTP requests can be successful or they can fail. They can also result in a state where the original intent was satisfied, but a side effect happened that should be conveyed back to the client.
To make it easier for clients to handle such an event, a Warning header using the warn-code "246" and the warn-text "Embedded Warning" MAY be returned. In this case, the client MAY either treat the response according to its HTTP status code, or the client MAY use the embedded warning information to understand the nature of the warning.
The "246" warn code does not prescribe the way in which warnings are represented, but the assumption is that the response will have embedded information that allows the client to learn about the nature of the warning. The following section describes a JSON structure that MAY be used to represent the warning. HTTP services are free to use this or other formats to represent the warning information they are embedding.
The JSON warning format uses the JSON format described in
. It is intended to be used as a building block in the response schemas of JSON-based APIs.
In many current designs of JSON-based HTTP APIs, services represent response data as members of the returned JSON object. In order to make it easier for consumers to identify information about warnings, a top-level member is defined that contains all warning information in a representation. A "warnings" member MUST encapsulate the warnings that will be returned to the client.
When an error occurred that can not be defined as a "hard error", but is meant as additional information one should consider returning this information to the APIs user. The warnings array MUST be filled with one object for each and every warning message that is returned to the client.
Entries in these individual objects follow the pattern described in .
When warnings are present a Warning header (as defined in )
SHOULD be set to indicate that warnings have be returned. This way a client will not
have to parse the response body to find out if the warnings array has entries.
Since warnings do not have an effect on the returned HTTP status code, the response status code SHOULD be in the 2xx range, indicating that the intent of the API client was successful.
As described previously, errors are exception like occurrences where processing of the request stopped and the API consumer has to be informed of this "hard error" right away.
To indicate this fact the content-type MAY be set to application/problem+json and detailed information about the error will be returned in the body following the pattern described in .
If warnings occurred during the processing of the request, but before the processing
stopped, they SHOULD be returned alongside the errors.
API providers need to exercise care when reporting warnings. Malicious actors could use this information for orchestrating attacks. Social engineering can also be a factor when warning information is returned by the API.
The HTTP warn code below has been registered by IANA per Section 7.2 of :Warn Code: 246Short Description: Embedded WarningReference: of [[ this document ]]Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the
specification. These words are often capitalized. This document defines these words as they should be
interpreted in IETF documents. This document specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and suggestions for improvements.
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for
distributed, collaborative, hypertext information systems. This document provides an
overview of HTTP architecture and its associated terminology, defines the "http"
and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1
message syntax and parsing requirements, and describes related security concerns for
implementations.Hypertext Transfer Protocol (HTTP/1.1): Semantics and ContentThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for
distributed, collaborative, hypertext information systems. This document defines the semantics of
HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes,
and response header fields, along with the payload of messages (metadata and body content) and
mechanisms for content negotiation.Hypertext Transfer Protocol (HTTP/1.1): Caching
The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed,
collaborative, hypertext information systems. This document defines HTTP caches and the associated
header fields that control cache behavior or indicate cacheable response messages.
Problem Details for HTTP APIs
This document defines a "problem detail" as a way to carry machine- readable details of errors in a HTTP
response to avoid the need to define new error response formats for HTTP APIs.
The JavaScript Object Notation (JSON) Data Interchange Format
JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data
interchange format. It was derived from the ECMAScript Programming Language Standard. JSON
defines a small set of formatting rules for the portable representation of structured data.
This document removes inconsistencies with other specifications of JSON, repairs specification
errors, and offers experience-based interoperability guidance.
Architecture of the World Wide Web, Volume OneThanks for comments and suggestions provided by ...