Communicating Warning Information in HTTP APIsshipcloud GmbHandre.cedik@googlemail.comAxwayerik.wilde@dret.nethttp://dret.net/netdret/
This document defines a new HTTP field Content-Warning and a standard response format for representing 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 failure) 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 success 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.
Note that this specification specifically targets warnings and not errors, meaning
that while it may be useful for clients to understand the warning condition and
act on it, they also may choose to ignore it and treat the response as a successful
one.
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 represent success, there is 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 communicate or embed 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 .
The Content-Warning field can be found in the header or trailer section (see Section 4.6 of ) of http responses and allows to represent different kinds of warning information via HTTP. It is defined as a Structured Header List . Its ABNF is:
Each member of the list MUST have exactly the two parameters "type" and "date".
The "type" parameter represents the warning that is being signaled. Its value is defined as a sh-token and SHOULD be a type that is registered in the Content-Warning type registry . Clients SHOULD ignore Content-Warning types that they do not know.The "date" parameter defines the last occurrence of this warning as a structured headers date as defined in (e.g. "1581410465").
Intermediaries of a response are not allowed to modify existing Content-Warning fields, but can add additional entries if warnings are produced while they are handling a response.
The Content-Warning Field is not tied to any specific HTTP request method, although specific values MAY only be used with a single or a subset of methods. The information as to which HTTP request methods are support for a single Content-Warning Type MUST be defined in the definition of the Content-Warning Type.
This document introduces the Content-Warning Type "embedded-warning".
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, the Content-Warning type "embedded-warning" MAY be returned. In this case, the client MAY either treat the response according to its HTTP status code, or in addition the client MAY use the embedded warning information to understand the nature of the warning.
The "embedded-warning" type does not prescribe the way in which warnings are represented. 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.
An exemplary Content-Warning field looks like this:
The embedded-warning Content-Warning Type infers, that there is more information in the responses body. Therefore all HTTP request methods that MAY have content in their body MAY also return embedded warnings.
HTTP request methods that do not return a body in their response SHOULD NOT return the embedded-warning Content-Warning Type.
The HTTP request method HEAD is an exception since it is allowed to return headers that are meant for being returned when sending a GET request. Therefore it MAY return the embedded-warning Content-Warning Type, although the body will be empty.
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 a condition occurs that can not be defined as a "hard error" (i.e., that allows clients to continue treating the resulting response as a success), additional information about this condition SHOULD be returned to the client. The "warnings" member MUST be an array that is structured 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 the Content-Warning field (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 whether a warnings member is present.
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 client was successful.
This example shows that the original intent was successful. If the original request was in fact not successful, a different status code SHOULD be returned. Embedded warnings are not tied to a specific http status code. Therefore they can be combined with every status code.
The Content-Warning field itself does not encourage a specific handling when it comes to caching responses. It is up to the Content-Warning type to specify if caching can be used or not.
The reasons for returning the Content-Warning Type "embedded-warning" can be manifold. A system could e.g. return warnings due to circumstances in the backend that can either still exist on subsequent requests or that have been solved in the meantime.
Intermediaries can fall into the same category. When a warning occurs, it can add warnings to the response making it possible to debug what happened at the intermediary. The reason for said warning can persist or may disappear on subsequent requests.
Therefore caching embedded-warnings SHOULD NOT be done. As one can't predict if the reason for returning embedded-warnings is still persistent.
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.
Clients processing warning information SHOULD make sure the right type of content was transmitted by checking the content-type header as well as the content-warning field. Content in the bodys warnings object SHOULD be processed accordingly. If no content-warning field was provided, clients are advised to ignore the content provided in the bodys warnings object.
As described in the embedded-warning Content-Warning type is expecting a body to be returned in the http response unless the HEAD method has been used for the request.
Therefore API clients SHOULD only parse a responses' body when the Content-Warning type is "embedded-warning". When the body is absent, a client SHOULD stop processing the response and return an adequate error message.
If an intermediary discovers a missing response body it MAY adjust the response to return a http status code of 500 - internal server error (see Section 6.6.1 of ).
When the response body does not contain warnings a client MAY use appropriate ways to inform the api provider about the fact. An error message MAY be
If an intermediary discovers missing warnings in the response body it MAY adjust the response to return warnings containing this information.
This specification registers the following entry in the Permanent Message Field Names registry established by :
Field name: Content-WarningApplicable protocol: HTTPStatus: standardAuthor/Change Controller: IETFSpecification document(s): [this document]Related information:
The "Content-Warning Type Registry" defines the namespace for new Content-Warning types. This specification establishes a new registry according to the guidelines given in . This new registry should not be included in an existing group of registries.
A registration MUST include the following fields:
Content-Warning Type: Name of the Content-Warning TypeReference: Pointer to a specification text
The registration policy for this registry is "Specification Required" as defined by , Section 4.6. They MUST follow the "sh-token" syntax defined by .
The registry has been populated with the registered values shown below:
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.
Registration Procedures for Message Header Fields
This specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. 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.
Guidelines for Writing an IANA Considerations Section in RFCsMany protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA).To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.This is the third edition of this document; it obsoletes RFC 5226.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.
Structured Headers for HTTP
This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header fields. It is intended for use by specifications of new HTTP header fields that wish to use a common syntax that is more restrictive than traditional HTTP field values.
Binary Structured HTTP Headers
This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header fields. It is intended for use by specifications of new HTTP header fields that wish to use a common syntax that is more restrictive than traditional HTTP field values.
HTTP SemanticsAdobe345 Park AveSan JoseCA95110United States of Americafielding@gbiv.comhttps://roy.gbiv.com/Fastlymnot@mnot.nethttps://www.mnot.net/greenbytes GmbHHafenweg 16Muenster48155Germanyjulian.reschke@greenbytes.dehttps://greenbytes.de/tech/webdav/Architecture of the World Wide Web, Volume OneThanks for comments and suggestions provided by Roy Fielding, Mark Nottingham, and Roberto Polli.