idnits 2.17.1
draft-cedik-http-warning-01.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 (March 30, 2020) is 1460 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 327, 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
** 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 (~~), 4 warnings (==), 2 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: October 1, 2020 Axway
6 March 30, 2020
8 Communicating Warning Information in HTTP APIs
9 draft-cedik-http-warning-01
11 Abstract
13 This document defines a new HTTP header field Content-Warning and a
14 standard response format for representing warning information in HTTP
15 APIs.
17 Note to Readers
19 This draft should be discussed on the rfc-interest mailing list
20 ().
22 Online access to all versions and files is available on GitHub
23 ().
25 Status of This Memo
27 This Internet-Draft is submitted in full conformance with the
28 provisions of BCP 78 and BCP 79.
30 Internet-Drafts are working documents of the Internet Engineering
31 Task Force (IETF). Note that other groups may also distribute
32 working documents as Internet-Drafts. The list of current Internet-
33 Drafts is at https://datatracker.ietf.org/drafts/current/.
35 Internet-Drafts are draft documents valid for a maximum of six months
36 and may be updated, replaced, or obsoleted by other documents at any
37 time. It is inappropriate to use Internet-Drafts as reference
38 material or to cite them other than as "work in progress."
40 This Internet-Draft will expire on October 1, 2020.
42 Copyright Notice
44 Copyright (c) 2020 IETF Trust and the persons identified as the
45 document authors. All rights reserved.
47 This document is subject to BCP 78 and the IETF Trust's Legal
48 Provisions Relating to IETF Documents
49 (https://trustee.ietf.org/license-info) in effect on the date of
50 publication of this document. Please review these documents
51 carefully, as they describe your rights and restrictions with respect
52 to this document. Code Components extracted from this document must
53 include Simplified BSD License text as described in Section 4.e of
54 the Trust Legal Provisions and are provided without warranty as
55 described in the Simplified BSD License.
57 Table of Contents
59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
60 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
61 3. Content-Warning Header Field . . . . . . . . . . . . . . . . 3
62 4. The "embedded-warning" Content-Warning Type . . . . . . . . . 4
63 5. JSON Warning Format . . . . . . . . . . . . . . . . . . . . . 4
64 6. Example with HTTP Header Field and Embedded Warning . . . . . 5
65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 6
66 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
67 8.1. HTTP Header Field Content-Warning . . . . . . . . . . . . 6
68 8.2. Content-Warning Type Registry . . . . . . . . . . . . . . 6
69 8.2.1. Registration Procedure . . . . . . . . . . . . . . . 6
70 8.2.2. Initial Registry Content . . . . . . . . . . . . . . 7
71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
72 9.1. Normative References . . . . . . . . . . . . . . . . . . 7
73 9.2. Informative References . . . . . . . . . . . . . . . . . 8
74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8
75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
77 1. Introduction
79 Many current APIs are based on HTTP [RFC7230] as their application
80 protocol. Their response handling model is based on the assumption
81 that requests either are successful or they fail. In both cases
82 (success and failure) an HTTP status code [RFC7231] is returned to
83 convey either fact.
85 But response status is not always strictly either success or failure.
86 For example, there are cases where an underlying system returns a
87 response with data that cannot be defined as a clear error. API
88 providers who are integrating such a service might want to return a
89 success response nonetheless, but returning a HTTP status code of
90 e.g. 200 OK without any additional information is not the only
91 possible approach in this case.
93 As defined in the principles of Web architecture
94 [W3C.REC-webarch-20041215], agents that "recover from errors by
95 making a choice without the user's consent are not acting on the
96 user's behalf". Therefore APIs should be able to communicate what
97 has happened to their consumers, which then allows clients or users
98 to make more informed decisions. Note that this specification
99 specifically targets warnings and not errors, meaning that while it
100 may be useful for clients to understand the warning condition and act
101 on it, they also may choose to ignore it and treat the response as a
102 successful one.
104 This document defines a warning code and a standard response
105 structure for communicating and representing warning information in
106 HTTP APIs. The goal is to allow HTTP providers to have a
107 standardized way of communicating to their consumers that while the
108 response can be considered to represent success, there is warning
109 information available that they might want to take into account.
111 As a general guideline, warning information should be considered to
112 be any information that can be safely ignored (treating the response
113 as if it did not communicate or embed any warning information), but
114 that might help clients and users to make better decisions.
116 2. Notational Conventions
118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
120 document are to be interpreted as described in [RFC2119].
122 3. Content-Warning Header Field
124 The Content-Warning header field allows to represent different kinds
125 of warning information via HTTP. It is defined as a Structured
126 Header List [I-D.ietf-httpbis-header-structure]. Its ABNF is:
128 Content-Warning = sh-list
130 Each member of the list MUST have exactly the two parameters "type"
131 and "date".
133 The "type" parameter represents the warning that is being
134 signaled. Its value is defined as a sh-token and SHOULD be a type
135 that is registered in the Content-Warning type registry
136 Section 8.2. Clients SHOULD ignore Content-Warning types that
137 they do not know.
139 The "date" parameter defines the last occurrence of this warning
140 as a structured headers date as defined in
141 [I-D.ietf-binary-structured-headers] (e.g. "1581410465").
143 4. The "embedded-warning" Content-Warning Type
145 This document introduces the Content-Warning Type "embedded-warning".
147 As mentioned in the introduction (Section 1), HTTP requests can be
148 successful or they can fail. They can also result in a state where
149 the original intent was satisfied, but a side effect happened that
150 should be conveyed back to the client.
152 To make it easier for clients to handle such an event, the Content-
153 Warning type "embedded-warning" MAY be returned. In this case, the
154 client MAY either treat the response according to its HTTP status
155 code, or in addition the client MAY use the embedded warning
156 information to understand the nature of the warning.
158 The "embedded-warning" type does not prescribe the way in which
159 warnings are represented. The assumption is that the response will
160 have embedded information that allows the client to learn about the
161 nature of the warning. The following section describes a JSON
162 structure that MAY be used to represent the warning. HTTP services
163 are free to use this or other formats to represent the warning
164 information they are embedding.
166 An exemplary Content-Warning header field looks like this:
168 Content-Warning: "embedded-warning"; 1590190500
170 5. JSON Warning Format
172 The JSON warning format uses the JSON format described in [RFC8259].
173 It is intended to be used as a building block in the response schemas
174 of JSON-based APIs.
176 In many current designs of JSON-based HTTP APIs, services represent
177 response data as members of the returned JSON object. In order to
178 make it easier for consumers to identify information about warnings,
179 a top-level member is defined that contains all warning information
180 in a representation. A "warnings" member MUST encapsulate the
181 warnings that will be returned to the client.
183 When an condition occurs that can not be defined as a "hard error"
184 (i.e., that allows clients to continue treating the resulting
185 response as a success), additional information about this condition
186 can be returned to the API client. The "warnings" member MUST be an
187 array that is structured with one object for each and every warning
188 message that is returned to the client.
190 Entries in these individual objects follow the pattern described in
191 [RFC7807].
193 When warnings are present the Content-Warning header field (as
194 defined in Section 3) SHOULD be set to indicate that warnings have be
195 returned. This way a client will not have to parse the response body
196 to find out whether a warnings member is present.
198 6. Example with HTTP Header Field and Embedded Warning
200 Since warnings do not have an effect on the returned HTTP status
201 code, the response status code SHOULD be in the 2xx range, indicating
202 that the intent of the API client was successful.
204 POST /example HTTP/1.1
205 Host: example.com
206 Accept: application/json
208 HTTP/1.1 200 OK
209 Content-Type: application/json
210 Content-Warning: "embedded-warning"; 1590190500
212 {
213 "request_id": "2326b087-d64e-43bd-a557-42171155084f",
214 "warnings": [
215 {
216 "detail": "Street name was too long. It has been shortened...",
217 "instance": "https://example.com/shipments/3a186c51/msgs/c94d",
218 "status": "200",
219 "title": "Street name too long. It has been shortened.",
220 "type": "https://example.com/errors/shortened_entry"
221 },
222 {
223 "detail": "City for this zipcode unknown. Code for shipment..",
224 "instance": "https://example.com/shipments/3a186c51/msgs/5927",
225 "status": "200",
226 "title": "City for zipcode unknown.",
227 "type": "https://example.com/errors/city_unknown"
228 }
229 ],
230 "id": "3a186c51d4281acb",
231 "carrier_tracking_no": "84168117830018",
232 "tracking_url": "http://example.com/3a186c51d",
233 "label_url": "http://example.com/shipping_label_3a186c51d.pdf",
234 "price": 3.4
235 }
237 7. Security Considerations
239 API providers need to exercise care when reporting warnings.
240 Malicious actors could use this information for orchestrating
241 attacks. Social engineering can also be a factor when warning
242 information is returned by the API.
244 8. IANA Considerations
246 8.1. HTTP Header Field Content-Warning
248 This specification registers the following entry in the Permanent
249 Message Header Field Names registry established by [RFC3864]:
251 o Header field name: Content-Warning
253 o Applicable protocol: HTTP
255 o Status: standard
257 o Author/Change Controller: IETF
259 o Specification document(s): [this document]
261 o Related information:
263 8.2. Content-Warning Type Registry
265 The "Content-Warning Type Registry" defines the namespace for new
266 Content-Warning types. This specification establishes a new registry
267 according to the guidelines given in [RFC8126]. This new registry
268 should not be included in an existing group of registries.
270 8.2.1. Registration Procedure
272 A registration MUST include the following fields:
274 o Content-Warning Type: Name of the Content-Warning Type
276 o Reference: Pointer to a specification text
278 The registration policy for this registry is "Specification Required"
279 as defined by [RFC8126], Section 4.6. They MUST follow the "sh-
280 token" syntax defined by [I-D.ietf-httpbis-header-structure].
282 8.2.2. Initial Registry Content
284 The registry has been populated with the registered values shown
285 below:
287 +------------------------+----------------------------------+
288 | Content-Warning Type | Reference |
289 +------------------------+----------------------------------+
290 | embedded-warning | this RFC, Section 4 |
291 +------------------------+----------------------------------+
293 9. References
295 9.1. Normative References
297 [I-D.ietf-binary-structured-headers]
298 Nottingham, M., "Binary Structured HTTP Headers", draft-
299 nottingham-binary-structured-headers-02 (work in
300 progress), March 2020.
302 [I-D.ietf-httpbis-header-structure]
303 Nottingham, M. and P. Kamp, "Structured Headers for HTTP",
304 draft-ietf-httpbis-header-structure-14 (work in progress),
305 October 2019.
307 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
308 Requirement Levels", BCP 14, RFC 2119,
309 DOI 10.17487/RFC2119, March 1997,
310 .
312 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
313 Procedures for Message Header Fields", BCP 90, RFC 3864,
314 DOI 10.17487/RFC3864, September 2004,
315 .
317 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
318 Protocol (HTTP/1.1): Message Syntax and Routing",
319 RFC 7230, DOI 10.17487/RFC7230, June 2014,
320 .
322 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
323 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
324 DOI 10.17487/RFC7231, June 2014,
325 .
327 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
328 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
329 RFC 7234, DOI 10.17487/RFC7234, June 2014,
330 .
332 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
333 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
334 .
336 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
337 Writing an IANA Considerations Section in RFCs", BCP 26,
338 RFC 8126, DOI 10.17487/RFC8126, June 2017,
339 .
341 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
342 Interchange Format", STD 90, RFC 8259,
343 DOI 10.17487/RFC8259, December 2017,
344 .
346 9.2. Informative References
348 [W3C.REC-webarch-20041215]
349 Jacobs, I. and N. Walsh, "Architecture of the World Wide
350 Web, Volume One", World Wide Web Consortium
351 Recommendation REC-webarch-20041215, December 2004,
352 .
354 Appendix A. Acknowledgements
356 Thanks for comments and suggestions provided by ...
358 Authors' Addresses
360 Andre Cedik
361 shipcloud GmbH
363 Email: andre.cedik@googlemail.com
365 Erik Wilde
366 Axway
368 Email: erik.wilde@dret.net
369 URI: http://dret.net/netdret/