idnits 2.17.1 draft-cedik-http-warning-00.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 (November 4, 2019) is 1633 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) ** 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 (~~), 1 warning (==), 1 comment (--). 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: May 7, 2020 Axway 6 November 4, 2019 8 Communicating Warning Information in HTTP APIs 9 draft-cedik-http-warning-00 11 Abstract 13 This document defines a warning code and a standard response format 14 for 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 May 7, 2020. 41 Copyright Notice 43 Copyright (c) 2019 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. Warning Header . . . . . . . . . . . . . . . . . . . . . . . 3 61 4. JSON Warning Format . . . . . . . . . . . . . . . . . . . . . 4 62 5. Correlation between errors, warnings and data . . . . . . . . 4 63 5.1. Soft errors with data . . . . . . . . . . . . . . . . . . 4 64 5.2. Hard errors with warnings . . . . . . . . . . . . . . . . 5 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 67 7.1. HTTP Warn Code: 246 - Embedded Warning . . . . . . . . . 6 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 70 8.2. Informative References . . . . . . . . . . . . . . . . . 7 71 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 74 1. Introduction 76 Many current APIs are based on HTTP [RFC7230] as their application 77 protocol. Their response handling model is based on the assumption 78 that requests either are successful or they fail. In both cases 79 (success and fail) an HTTP status code [RFC7231] is returned to 80 convey either fact. 82 But response status is not always strictly either success or failure. 83 For example, there are cases where an underlying system returns a 84 response with data that cannot be defined as a clear error. API 85 providers who are integrating such a service might want to return a 86 correct response nonetheless, but returning a HTTP status code of 87 e.g. 200 OK without any additional information is not the only 88 possible approach in this case. 90 As defined in the principles of Web architecture 91 [W3C.REC-webarch-20041215], agents that "recover from errors by 92 making a choice without the user's consent are not acting on the 93 user's behalf". Therefore APIs should be able to communicate what 94 has happened to their consumers, which then allows clients or users 95 to make more informed decisions. 97 This document defines a warning code and a standard response 98 structure for communicating and representing warning information in 99 HTTP APIs. The goal is to allow HTTP providers to have a 100 standardized way of communicating to their consumers that while the 101 response can be considered to be a non-failure, there is some warning 102 information available that they might want to take into account. 104 As a general guideline, warning information should be considered to 105 be any information that can be safely ignored (treating the response 106 as if it did not contain any warning information), but that might 107 help clients and users to make better decisions. 109 2. Notational Conventions 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 3. Warning Header 117 As described in section 5.5 of [RFC7234] the Warning header field "is 118 used to carry additional information about the status or 119 transformation of a message that might not be reflected in the status 120 code". The field itself consists of the warn-code, a warn-agent, a 121 warn-text, and an optional warn-date. 123 As mentioned in the introduction (Section 1), HTTP requests can be 124 successful or they can fail. They can also result in a state where 125 the original intent was satisfied, but a side effect happened that 126 should be conveyed back to the client. 128 To make it easier for clients to handle such an event, a Warning 129 header using the warn-code "246" and the warn-text "Embedded Warning" 130 MAY be returned. In this case, the client MAY either treat the 131 response according to its HTTP status code, or the client MAY use the 132 embedded warning information to understand the nature of the warning. 134 The "246" warn code does not prescribe the way in which warnings are 135 represented, but the assumption is that the response will have 136 embedded information that allows the client to learn about the nature 137 of the warning. The following section describes a JSON structure 138 that MAY be used to represent the warning. HTTP services are free to 139 use this or other formats to represent the warning information they 140 are embedding. 142 4. JSON Warning Format 144 The JSON warning format uses the JSON format described in [RFC8259]. 145 It is intended to be used as a building block in the response schemas 146 of JSON-based APIs. 148 In many current designs of JSON-based HTTP APIs, services represent 149 response data as members of the returned JSON object. In order to 150 make it easier for consumers to identify information about warnings, 151 a top-level member is defined that contains all warning information 152 in a representation. A "warnings" member MUST encapsulate the 153 warnings that will be returned to the client. 155 When an error occurred that can not be defined as a "hard error", but 156 is meant as additional information one should consider returning this 157 information to the APIs user. The warnings array MUST be filled with 158 one object for each and every warning message that is returned to the 159 client. 161 Entries in these individual objects follow the pattern described in 162 [RFC7807]. 164 When warnings are present a Warning header (as defined in Section 3) 165 SHOULD be set to indicate that warnings have be returned. This way a 166 client will not have to parse the response body to find out if the 167 warnings array has entries. 169 5. Correlation between errors, warnings and data 171 5.1. Soft errors with data 173 Since warnings do not have an effect on the returned HTTP status 174 code, the response status code SHOULD be in the 2xx range, indicating 175 that the intent of the API client was successful. 177 POST /example HTTP/1.1 178 Host: example.com 179 Accept: application/json 181 HTTP/1.1 200 OK 182 Content-Type: application/json 183 Warning: 246 - "Embedded Warning" "Fri, 04 Oct 2019 09:59:45 GMT" 185 { 186 "request_id": "2326b087-d64e-43bd-a557-42171155084f", 187 "warnings": [ 188 { 189 "detail": "Street name was too long. It has been shortened...", 190 "instance": "https://example.com/shipments/3a186c51/msgs/c94d", 191 "status": "200", 192 "title": "Street name too long. It has been shortened.", 193 "type": "https://example.com/errors/shortened_entry" 194 }, 195 { 196 "detail": "City for this zipcode unknown. Code for shipment..", 197 "instance": "https://example.com/shipments/3a186c51/msgs/5927", 198 "status": "200", 199 "title": "City for zipcode unknown.", 200 "type": "https://example.com/errors/city_unknown" 201 } 202 ], 203 "id": "3a186c51d4281acb", 204 "carrier_tracking_no": "84168117830018", 205 "tracking_url": "http://example.com/3a186c51d", 206 "label_url": "http://example.com/shipping_label_3a186c51d.pdf", 207 "price": 3.4 208 } 210 5.2. Hard errors with warnings 212 As described previously, errors are exception like occurrences where 213 processing of the request stopped and the API consumer has to be 214 informed of this "hard error" right away. 216 To indicate this fact the content-type MAY be set to application/ 217 problem+json and detailed information about the error will be 218 returned in the body following the pattern described in [RFC7807]. 220 If warnings occurred during the processing of the request, but before 221 the processing stopped, they SHOULD be returned alongside the errors. 223 POST /example HTTP/1.1 224 Host: example.com 225 Accept: application/json 227 HTTP/1.1 400 BAD REQUEST 228 Content-Type: application/problem+json 229 Warning: 246 - "Embedded Warning" "Fri, 04 Oct 2019 09:59:45 GMT" 231 { 232 "request_id": "2326b087-d64e-43bd-a557-42171155084f", 233 "detail": "The format of pickup time earliest was wrong.", 234 "status": "500", 235 "title": "Wrong format for pickup time", 236 "type": "https://example.com/errors/wrong_format" 237 "warnings": [ 238 { 239 "detail": "Street name too long. It has been shortened to fit", 240 "status": "200", 241 "title": "Street name too long. It has been shortened.", 242 "type": "https://example.com/errors/shortened_entry" 243 } 244 ] 245 } 247 6. Security Considerations 249 API providers need to exercise care when reporting warnings. 250 Malicious actors could use this information for orchestrating 251 attacks. Social engineering can also be a factor when warning 252 information is returned by the API. 254 7. IANA Considerations 256 7.1. HTTP Warn Code: 246 - Embedded Warning 258 The HTTP warn code below has been registered by IANA per Section 7.2 259 of [RFC7234]: 261 Warn Code: 246 263 Short Description: Embedded Warning 265 Reference: Section 3 of [[ this document ]] 267 8. References 269 8.1. Normative References 271 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 272 Requirement Levels", BCP 14, RFC 2119, 273 DOI 10.17487/RFC2119, March 1997, 274 . 276 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 277 Protocol (HTTP/1.1): Message Syntax and Routing", 278 RFC 7230, DOI 10.17487/RFC7230, June 2014, 279 . 281 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 282 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 283 DOI 10.17487/RFC7231, June 2014, 284 . 286 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 287 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 288 RFC 7234, DOI 10.17487/RFC7234, June 2014, 289 . 291 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 292 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 293 . 295 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 296 Interchange Format", STD 90, RFC 8259, 297 DOI 10.17487/RFC8259, December 2017, 298 . 300 8.2. Informative References 302 [W3C.REC-webarch-20041215] 303 Jacobs, I. and N. Walsh, "Architecture of the World Wide 304 Web, Volume One", World Wide Web Consortium 305 Recommendation REC-webarch-20041215, December 2004, 306 . 308 Appendix A. Acknowledgements 310 Thanks for comments and suggestions provided by ... 312 Authors' Addresses 314 Andre Cedik 315 shipcloud GmbH 317 Email: andre.cedik@googlemail.com 319 Erik Wilde 320 Axway 322 Email: erik.wilde@dret.net 323 URI: http://dret.net/netdret/