idnits 2.17.1 draft-activity-identifiers-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 : ---------------------------------------------------------------------------- ** There are 45 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 23, 2019) is 1800 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? 'RFC2119' on line 102 looks like a reference Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Individual S. Perham 2 Internet Draft 3 Intended status: Informational May 23, 2019 4 Expires: November 23, 2019 6 Hypertext Transfer Protocol (HTTP/1.1): Activity Identifiers 7 draft-activity-identifiers-01 9 Status of this Memo 11 This Internet-Draft is submitted in full conformance with the 12 provisions of BCP 78 and BCP 79. This document may not be modified, 13 and derivative works of it may not be created, except to publish it 14 as an RFC and to translate it into languages other than English. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other documents 23 at any time. It is inappropriate to use Internet-Drafts as 24 reference material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html 32 This Internet-Draft will expire on November 23, 2019. 34 Copyright Notice 36 Copyright (c) 2016 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with 44 respect to this document. 46 Abstract 48 It is very common that implementers of HTTP severs require the ability 49 to associate an identifier to an HTTP request and or response, this can 50 be for a number of reasons which could include checking for duplicate 51 requests, allowing the caller of an API to maintain a record of their 52 interaction with the server or to track client/server requests through 53 a disparate system of services. In any case, the implementer will quite 54 often use a custom HTTP header and either assign a value itself or 55 require the caller to supply the value. This document outlines a 56 consistent storage mechanism for this identifier by way of a standard 57 HTTP header and a new status code for when a mandated identifier is 58 omitted. The purpose is to create better consistency for clients of 59 third-party HTTP servers and HTTP based APIs by introducing this 60 standard request and response header. 62 Table of Contents 64 1. Introduction ................................................ 3 65 1.1. Conventions used in this document....................... 3 66 2. Activity Identifiers......................................... 3 67 2.1. Activity-Id message header.............................. 3 68 2.2. Response header......................................... 3 69 2.3. Value considerations.................................... 4 70 3. Status code definitions...................................... 4 71 3.1. 435 Missing Activity Id................................. 4 72 4. Security Considerations...................................... 4 73 5. IANA Considerations ......................................... 4 74 5.1. Header Field Registration............................... 4 75 5.2. Status Code Registration................................ 4 76 6. Conclusions ................................................. 5 77 7. References .................................................. 5 78 7.1. Normative References.................................... 5 79 7.2. Informative References.................................. 5 80 8. Acknowledgments ............................................. 5 82 1. Introduction 84 Implementers of HTTP clients and servers often encounter the need to 85 track unique requests through the system and identify potential 86 duplicate requests to enable an idempotent behavior. This document 87 defines HTTP/1.1 activity identifiers to address these requirements in 88 a consistent manner. 90 Activity identifiers are an OPTIONAL feature of HTTP and as such either 91 the sender or receiver of a request can include it without adversely 92 impacting the request should the opposite party not be expecting it. 94 This document also describes the scenario whereby a server implementer 95 deems the header REQUIRED and is omitted by the caller. 97 1.1. Conventions used in this document 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 document are to be interpreted as described in RFC 2119 [RFC2119]. 103 2. Activity Identifiers 105 2.1. Activity-Id Message Header 107 The header MAY be included as a HTTP message header in requests and 108 responses. The format of the header is as follows: 110 Activity-Id: 112 The value of being any value that conforms to the 113 header format values as defined in Message syntax and routing [7230 114 Section 3.2.6] 116 2.2. Response Header 118 In the case where a sender included an activity id value, the 119 receiver SHOULD include a duplicate value in the Activity-Id header 120 of the response message. 122 In the case where the sender omitted an activity id value, the 123 receiver MAY include a server generated identifier instead. 125 2.3. Value Considerations 127 It is RECOMMENDED that the originator of an activity id ensure that 128 the value conforms to the UUID standard [see 4122] so as to minimize 129 false duplicates. 131 3. Status Code Definitions 133 3.1. 435 Missing Activity Id 135 Although the Activity-Id header is OPTIONAL, some HTTP server 136 implementers MAY deem it necessary to enforce that the sending party 137 include the header and a valid value. In the case where its 138 inclusion has been deemed mandatory AND the sender has omitted the 139 header or its value, then the server SHOULD present the sender with 140 a 435 response code. 142 4. Security Considerations 144 As with other HTTP message headers, the protection of the value 145 defined for this header is outside the scope of this document and no 146 recommendation is made for encoding any form of sensitive 147 information. 149 5. IANA Considerations 151 5.1. Header Field Registration 153 HTTP header fields are registered within the "Message Headers" 154 registry maintained at http://www.iana.org/assignments/message- 155 headers/ 157 This document defines the following HTTP header fields: 159 +-------------------+----------+----------+-------------+ 160 | Header Field Name | Protocol | Status | Reference | 161 +-------------------+----------+----------+-------------+ 162 | Activity-Id | http | standard | Section 2.1.| 163 +-------------------+----------+----------+-------------+ 165 5.2. Status Code Registration 167 +-------+-----------------------+-------------+ 168 | Value | Description | Reference | 169 +-------+-----------------------+-------------+ 170 | 435 | Missing Activity Id | Section 3.1.| 171 +-------+-----------------------+-------------+ 173 6. Conclusions 175 7. References 177 7.1. Normative References 179 7.2. Informative References 181 8. Acknowledgments 183 This document was prepared using 2-Word-v2.0.template.dot. 185 Authors' Addresses 187 Scott Perham 188 71a Stoneleigh Broadway 189 Epsom 190 Surrey 191 KT17 2HP 192 UK 194 Phone: 07545 826507 195 Email: scott@polystream.com