idnits 2.17.1
draft-cedik-http-warning-02.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (September 24, 2020) is 1310 days in the past. Is
this intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: 'RFC7234' is defined on line 426, but no explicit
reference was found in the text
== Outdated reference: A later version (-03) exists of
draft-nottingham-binary-structured-headers-02
-- Possible downref: Normative reference to a draft: ref.
'I-D.ietf-binary-structured-headers'
== Outdated reference: A later version (-19) exists of
draft-ietf-httpbis-header-structure-14
== Outdated reference: A later version (-19) exists of
draft-ietf-httpbis-semantics-07
-- Possible downref: Normative reference to a draft: ref.
'I-D.ietf-httpbis-semantics'
** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112)
** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110)
** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111)
** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457)
Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group A. Cedik
3 Internet-Draft shipcloud GmbH
4 Intended status: Standards Track E. Wilde
5 Expires: March 28, 2021 Axway
6 September 24, 2020
8 Communicating Warning Information in HTTP APIs
9 draft-cedik-http-warning-02
11 Abstract
13 This document defines a new HTTP field Content-Warning and a standard
14 response format for representing warning information in HTTP APIs.
16 Note to Readers
18 This draft should be discussed on the rfc-interest mailing list
19 ().
21 Online access to all versions and files is available on GitHub
22 ().
24 Status of This Memo
26 This Internet-Draft is submitted in full conformance with the
27 provisions of BCP 78 and BCP 79.
29 Internet-Drafts are working documents of the Internet Engineering
30 Task Force (IETF). Note that other groups may also distribute
31 working documents as Internet-Drafts. The list of current Internet-
32 Drafts is at https://datatracker.ietf.org/drafts/current/.
34 Internet-Drafts are draft documents valid for a maximum of six months
35 and may be updated, replaced, or obsoleted by other documents at any
36 time. It is inappropriate to use Internet-Drafts as reference
37 material or to cite them other than as "work in progress."
39 This Internet-Draft will expire on March 28, 2021.
41 Copyright Notice
43 Copyright (c) 2020 IETF Trust and the persons identified as the
44 document authors. All rights reserved.
46 This document is subject to BCP 78 and the IETF Trust's Legal
47 Provisions Relating to IETF Documents
48 (https://trustee.ietf.org/license-info) in effect on the date of
49 publication of this document. Please review these documents
50 carefully, as they describe your rights and restrictions with respect
51 to this document. Code Components extracted from this document must
52 include Simplified BSD License text as described in Section 4.e of
53 the Trust Legal Provisions and are provided without warranty as
54 described in the Simplified BSD License.
56 Table of Contents
58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
59 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
60 3. Content-Warning Field . . . . . . . . . . . . . . . . . . . . 3
61 3.1. HTTP request methods . . . . . . . . . . . . . . . . . . 4
62 4. The "embedded-warning" Content-Warning Type . . . . . . . . . 4
63 4.1. Allowed HTTP request methods for embedded-warning . . . . 4
64 5. JSON Warning Format . . . . . . . . . . . . . . . . . . . . . 5
65 6. Example with HTTP Field and Embedded Warning . . . . . . . . 5
66 7. Cache Considerations . . . . . . . . . . . . . . . . . . . . 6
67 7.1. Caching the "embedded-warning" Content-Warning type . . . 7
68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7
69 8.1. Absence of a response body . . . . . . . . . . . . . . . 7
70 8.2. Absence of warnings in the response body . . . . . . . . 8
71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
72 9.1. HTTP Field Content-Warning . . . . . . . . . . . . . . . 8
73 9.2. Content-Warning Type Registry . . . . . . . . . . . . . . 8
74 9.2.1. Registration Procedure . . . . . . . . . . . . . . . 8
75 9.2.2. Initial Registry Content . . . . . . . . . . . . . . 9
76 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
77 10.1. Normative References . . . . . . . . . . . . . . . . . . 9
78 10.2. Informative References . . . . . . . . . . . . . . . . . 10
79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
82 1. Introduction
84 Many current APIs are based on HTTP [RFC7230] as their application
85 protocol. Their response handling model is based on the assumption
86 that requests either are successful or they fail. In both cases
87 (success and failure) an HTTP status code [RFC7231] is returned to
88 convey either fact.
90 But response status is not always strictly either success or failure.
91 For example, there are cases where an underlying system returns a
92 response with data that cannot be defined as a clear error. API
93 providers who are integrating such a service might want to return a
94 success response nonetheless, but returning a HTTP status code of
95 e.g. 200 OK without any additional information is not the only
96 possible approach in this case.
98 As defined in the principles of Web architecture
99 [W3C.REC-webarch-20041215], agents that "recover from errors by
100 making a choice without the user's consent are not acting on the
101 user's behalf". Therefore APIs should be able to communicate what
102 has happened to their consumers, which then allows clients or users
103 to make more informed decisions. Note that this specification
104 specifically targets warnings and not errors, meaning that while it
105 may be useful for clients to understand the warning condition and act
106 on it, they also may choose to ignore it and treat the response as a
107 successful one.
109 This document defines a warning code and a standard response
110 structure for communicating and representing warning information in
111 HTTP APIs. The goal is to allow HTTP providers to have a
112 standardized way of communicating to their consumers that while the
113 response can be considered to represent success, there is warning
114 information available that they might want to take into account.
116 As a general guideline, warning information should be considered to
117 be any information that can be safely ignored (treating the response
118 as if it did not communicate or embed any warning information), but
119 that might help clients and users to make better decisions.
121 2. Notational Conventions
123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
125 document are to be interpreted as described in [RFC2119].
127 3. Content-Warning Field
129 The Content-Warning field can be found in the header or trailer
130 section (see Section 4.6 of [I-D.ietf-httpbis-semantics]) of http
131 responses and allows to represent different kinds of warning
132 information via HTTP. It is defined as a Structured Header List
133 [I-D.ietf-httpbis-header-structure]. Its ABNF is:
135 Content-Warning = sh-list
137 Each member of the list MUST have exactly the two parameters "type"
138 and "date".
140 o The "type" parameter represents the warning that is being
141 signaled. Its value is defined as a sh-token and SHOULD be a type
142 that is registered in the Content-Warning type registry
143 Section 9.2. Clients SHOULD ignore Content-Warning types that
144 they do not know.
146 o The "date" parameter defines the last occurrence of this warning
147 as a structured headers date as defined in
148 [I-D.ietf-binary-structured-headers] (e.g. "1581410465").
150 Intermediaries of a response are not allowed to modify existing
151 Content-Warning fields, but can add additional entries if warnings
152 are produced while they are handling a response.
154 3.1. HTTP request methods
156 The Content-Warning Field is not tied to any specific HTTP request
157 method, although specific values MAY only be used with a single or a
158 subset of methods. The information as to which HTTP request methods
159 are support for a single Content-Warning Type MUST be defined in the
160 definition of the Content-Warning Type.
162 4. The "embedded-warning" Content-Warning Type
164 This document introduces the Content-Warning Type "embedded-warning".
166 As mentioned in the introduction (Section 1), HTTP requests can be
167 successful or they can fail. They can also result in a state where
168 the original intent was satisfied, but a side effect happened that
169 should be conveyed back to the client.
171 To make it easier for clients to handle such an event, the Content-
172 Warning type "embedded-warning" MAY be returned. In this case, the
173 client MAY either treat the response according to its HTTP status
174 code, or in addition the client MAY use the embedded warning
175 information to understand the nature of the warning.
177 The "embedded-warning" type does not prescribe the way in which
178 warnings are represented. The assumption is that the response will
179 have embedded information that allows the client to learn about the
180 nature of the warning. The following section describes a JSON
181 structure that MAY be used to represent the warning. HTTP services
182 are free to use this or other formats to represent the warning
183 information they are embedding.
185 An exemplary Content-Warning field looks like this:
187 Content-Warning: "embedded-warning"; 1590190500
189 4.1. Allowed HTTP request methods for embedded-warning
191 The embedded-warning Content-Warning Type infers, that there is more
192 information in the responses body. Therefore all HTTP request
193 methods that MAY have content in their body MAY also return embedded
194 warnings.
196 HTTP request methods that do not return a body in their response
197 SHOULD NOT return the embedded-warning Content-Warning Type.
199 The HTTP request method HEAD is an exception since it is allowed to
200 return headers that are meant for being returned when sending a GET
201 request. Therefore it MAY return the embedded-warning Content-
202 Warning Type, although the body will be empty.
204 5. JSON Warning Format
206 The JSON warning format uses the JSON format described in [RFC8259].
207 It is intended to be used as a building block in the response schemas
208 of JSON-based APIs.
210 In many current designs of JSON-based HTTP APIs, services represent
211 response data as members of the returned JSON object. In order to
212 make it easier for consumers to identify information about warnings,
213 a top-level member is defined that contains all warning information
214 in a representation. A "warnings" member MUST encapsulate the
215 warnings that will be returned to the client.
217 When a condition occurs that can not be defined as a "hard error"
218 (i.e., that allows clients to continue treating the resulting
219 response as a success), additional information about this condition
220 SHOULD be returned to the client. The "warnings" member MUST be an
221 array that is structured with one object for each and every warning
222 message that is returned to the client.
224 Entries in these individual objects follow the pattern described in
225 [RFC7807].
227 When warnings are present the Content-Warning field (as defined in
228 Section 3) SHOULD be set to indicate that warnings have be returned.
229 This way a client will not have to parse the response body to find
230 out whether a warnings member is present.
232 6. Example with HTTP Field and Embedded Warning
234 Since warnings do not have an effect on the returned HTTP status
235 code, the response status code SHOULD be in the 2xx range, indicating
236 that the intent of the client was successful.
238 POST /example HTTP/1.1
239 Host: example.com
240 Accept: application/json
242 HTTP/1.1 200 OK
243 Content-Type: application/json
244 Content-Warning: "embedded-warning"; 1590190500
246 {
247 "request_id": "2326b087-d64e-43bd-a557-42171155084f",
248 "warnings": [
249 {
250 "detail": "Street name was too long. It has been shortened...",
251 "instance": "https://example.com/shipments/3a186c51/msgs/c94d",
252 "status": "200",
253 "title": "Street name too long. It has been shortened.",
254 "type": "https://example.com/errors/shortened_entry"
255 },
256 {
257 "detail": "City for this zipcode unknown. Code for shipment..",
258 "instance": "https://example.com/shipments/3a186c51/msgs/5927",
259 "status": "200",
260 "title": "City for zipcode unknown.",
261 "type": "https://example.com/errors/city_unknown"
262 }
263 ],
264 "id": "3a186c51d4281acb",
265 "carrier_tracking_no": "84168117830018",
266 "tracking_url": "http://example.com/3a186c51d",
267 "label_url": "http://example.com/shipping_label_3a186c51d.pdf",
268 "price": 3.4
269 }
271 This example shows that the original intent was successful. If the
272 original request was in fact not successful, a different status code
273 SHOULD be returned. Embedded warnings are not tied to a specific
274 http status code. Therefore they can be combined with every status
275 code.
277 7. Cache Considerations
279 The Content-Warning field itself does not encourage a specific
280 handling when it comes to caching responses. It is up to the
281 Content-Warning type to specify if caching can be used or not.
283 7.1. Caching the "embedded-warning" Content-Warning type
285 The reasons for returning the Content-Warning Type "embedded-warning"
286 can be manifold. A system could e.g. return warnings due to
287 circumstances in the backend that can either still exist on
288 subsequent requests or that have been solved in the meantime.
290 Intermediaries can fall into the same category. When a warning
291 occurs, it can add warnings to the response making it possible to
292 debug what happened at the intermediary. The reason for said warning
293 can persist or may disappear on subsequent requests.
295 Therefore caching embedded-warnings SHOULD NOT be done. As one can't
296 predict if the reason for returning embedded-warnings is still
297 persistent.
299 8. Security Considerations
301 API providers need to exercise care when reporting warnings.
302 Malicious actors could use this information for orchestrating
303 attacks. Social engineering can also be a factor when warning
304 information is returned by the API.
306 Clients processing warning information SHOULD make sure the right
307 type of content was transmitted by checking the content-type header
308 as well as the content-warning field. Content in the bodys warnings
309 object SHOULD be processed accordingly. If no content-warning field
310 was provided, clients are advised to ignore the content provided in
311 the bodys warnings object.
313 8.1. Absence of a response body
315 As described in Section 4.1 the embedded-warning Content-Warning type
316 is expecting a body to be returned in the http response unless the
317 HEAD method has been used for the request.
319 Therefore API clients SHOULD only parse a responses' body when the
320 Content-Warning type is "embedded-warning". When the body is absent,
321 a client SHOULD stop processing the response and return an adequate
322 error message.
324 If an intermediary discovers a missing response body it MAY adjust
325 the response to return a http status code of 500 - internal server
326 error (see Section 6.6.1 of [RFC7231]).
328 8.2. Absence of warnings in the response body
330 When the response body does not contain warnings a client MAY use
331 appropriate ways to inform the api provider about the fact. An error
332 message MAY be
334 If an intermediary discovers missing warnings in the response body it
335 MAY adjust the response to return warnings containing this
336 information.
338 9. IANA Considerations
340 9.1. HTTP Field Content-Warning
342 This specification registers the following entry in the Permanent
343 Message Field Names registry established by [RFC3864]:
345 o Field name: Content-Warning
347 o Applicable protocol: HTTP
349 o Status: standard
351 o Author/Change Controller: IETF
353 o Specification document(s): [this document]
355 o Related information:
357 9.2. Content-Warning Type Registry
359 The "Content-Warning Type Registry" defines the namespace for new
360 Content-Warning types. This specification establishes a new registry
361 according to the guidelines given in [RFC8126]. This new registry
362 should not be included in an existing group of registries.
364 9.2.1. Registration Procedure
366 A registration MUST include the following fields:
368 o Content-Warning Type: Name of the Content-Warning Type
370 o Reference: Pointer to a specification text
372 The registration policy for this registry is "Specification Required"
373 as defined by [RFC8126], Section 4.6. They MUST follow the "sh-
374 token" syntax defined by [I-D.ietf-httpbis-header-structure].
376 9.2.2. Initial Registry Content
378 The registry has been populated with the registered values shown
379 below:
381 +------------------------+----------------------------------+
382 | Content-Warning Type | Reference |
383 +------------------------+----------------------------------+
384 | embedded-warning | this RFC, Section 4 |
385 +------------------------+----------------------------------+
387 10. References
389 10.1. Normative References
391 [I-D.ietf-binary-structured-headers]
392 Nottingham, M., "Binary Structured HTTP Headers", draft-
393 nottingham-binary-structured-headers-02 (work in
394 progress), March 2020.
396 [I-D.ietf-httpbis-header-structure]
397 Nottingham, M. and P. Kamp, "Structured Headers for HTTP",
398 draft-ietf-httpbis-header-structure-14 (work in progress),
399 October 2019.
401 [I-D.ietf-httpbis-semantics]
402 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
403 Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-07
404 (work in progress), March 2020.
406 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
407 Requirement Levels", BCP 14, RFC 2119,
408 DOI 10.17487/RFC2119, March 1997,
409 .
411 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
412 Procedures for Message Header Fields", BCP 90, RFC 3864,
413 DOI 10.17487/RFC3864, September 2004,
414 .
416 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
417 Protocol (HTTP/1.1): Message Syntax and Routing",
418 RFC 7230, DOI 10.17487/RFC7230, June 2014,
419 .
421 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
422 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
423 DOI 10.17487/RFC7231, June 2014,
424 .
426 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
427 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
428 RFC 7234, DOI 10.17487/RFC7234, June 2014,
429 .
431 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
432 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
433 .
435 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
436 Writing an IANA Considerations Section in RFCs", BCP 26,
437 RFC 8126, DOI 10.17487/RFC8126, June 2017,
438 .
440 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
441 Interchange Format", STD 90, RFC 8259,
442 DOI 10.17487/RFC8259, December 2017,
443 .
445 10.2. Informative References
447 [W3C.REC-webarch-20041215]
448 Jacobs, I. and N. Walsh, "Architecture of the World Wide
449 Web, Volume One", World Wide Web Consortium
450 Recommendation REC-webarch-20041215, December 2004,
451 .
453 Appendix A. Acknowledgements
455 Thanks for comments and suggestions provided by Roy Fielding, Mark
456 Nottingham, and Roberto Polli.
458 Authors' Addresses
460 Andre Cedik
461 shipcloud GmbH
463 Email: andre.cedik@googlemail.com
464 Erik Wilde
465 Axway
467 Email: erik.wilde@dret.net
468 URI: http://dret.net/netdret/