Individual S. Perham Internet Draft Intended status: Informational March 18, 2016 Expires: MAR 2017 Hypertext Transfer Protocol (HTTP/1.1): Activity Identifiers draft-activity-identifiers-00 Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. This document may not be modified, and derivative works of it may not be created, except to publish it as an RFC and to translate it into languages other than English. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This Internet-Draft will expire on MAR 18, 2017. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Perham Expires March 18, 2017 [Page 1] Internet-Draft Activity Identifiers March 2016 Abstract It is very common that implementers of HTTP severs require the ability to associate an identifier to an HTTP request and or response, this can be for a number of reasons which could include checking for duplicate requests, allowing the caller of an API to maintain a record of their interaction with the server or to track client/server requests through a disparate system of services. In any case, the implementer will quite often use a custom HTTP header and either assign a value itself or require the caller to supply the value. This document outlines a consistent storage mechanism for this identifier by way of a standard HTTP header and a new status code for when a mandated identifier is omitted. The purpose is to create better consistency for clients of third-party HTTP servers and HTTP based APIs by introducing this standard request and response header. Table of Contents 1. Introduction ................................................ 3 1.1. Conventions used in this document....................... 3 2. Activity Identifiers......................................... 3 2.1. Activity-Id message header.............................. 3 2.2. Response header......................................... 3 2.3. Value considerations.................................... 4 3. Status code definitions...................................... 4 3.1. 435 Missing Activity Id................................. 4 4. Security Considerations...................................... 4 5. IANA Considerations ......................................... 4 5.1. Header Field Registration............................... 4 5.2. Status Code Registration................................ 4 6. Conclusions ................................................. 5 7. References .................................................. 5 7.1. Normative References.................................... 5 7.2. Informative References.................................. 5 8. Acknowledgments ............................................. 5 Perham Expires March 18, 2017 [Page 2] Internet-Draft Activity Identifiers March 2016 1. Introduction Implementers of HTTP clients and servers often encounter the need to track unique requests through the system and identify potential duplicate requests to enable an idempotent behavior. This document defines HTTP/1.1 activity identifiers to address these requirements in a consistent manner. Activity identifiers are an OPTIONAL feature of HTTP and as such either the sender or receiver of a request can include it without adversely impacting the request should the opposite party not be expecting it. This document also describes the scenario whereby a server implementer deems the header REQUIRED and is omitted by the caller. 1.1. Conventions used in this document 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 RFC 2119 [RFC2119]. 2. Activity Identifiers 2.1. Activity-Id Message Header The header MAY be included as a HTTP message header in requests and responses. The format of the header is as follows: Activity-Id: The value of being any value that conforms to the header format values as defined in Message syntax and routing [7230 Section 3.2.6] 2.2. Response Header In the case where a sender included an activity id value, the receiver SHOULD include a duplicate value in the Activity-Id header of the response message. In the case where the sender omitted an activity id value, the receiver MAY include a server generated identifier instead. Perham Expires March 18, 2017 [Page 3] Internet-Draft Activity Identifiers March 2016 2.3. Value Considerations It is RECOMMENDED that the originator of an activity id ensure that the value conforms to the UUID standard [see 4122] so as to minimize false duplicates. 3. Status Code Definitions 3.1. 435 Missing Activity Id Although the Activity-Id header is OPTIONAL, some HTTP server implementers MAY deem it necessary to enforce that the sending party include the header and a valid value. In the case where its inclusion has been deemed mandatory AND the sender has omitted the header or its value, then the server SHOULD present the sender with a 435 response code. 4. Security Considerations As with other HTTP message headers, the protection of the value defined for this header is outside the scope of this document and no recommendation is made for encoding any form of sensitive information. 5. IANA Considerations 5.1. Header Field Registration HTTP header fields are registered within the "Message Headers" registry maintained at http://www.iana.org/assignments/message- headers/ This document defines the following HTTP header fields: +-------------------+----------+----------+-------------+ | Header Field Name | Protocol | Status | Reference | +-------------------+----------+----------+-------------+ | Activity-Id | http | standard | Section 2.1.| +-------------------+----------+----------+-------------+ 5.2. Status Code Registration +-------+-----------------------+-------------+ | Value | Description | Reference | +-------+-----------------------+-------------+ | 435 | Missing Activity Id | Section 3.1.| +-------+-----------------------+-------------+ Perham Expires March 18, 2017 [Page 4] Internet-Draft Activity Identifiers March 2016 6. Conclusions 7. References 7.1. Normative References 7.2. Informative References 8. Acknowledgments This document was prepared using 2-Word-v2.0.template.dot. Perham Expires March 18, 2017 [Page 5] Internet-Draft Activity Identifiers March 2016 Authors' Addresses Scott Perham 361 Kingston Road Ewell Surrey KT19 0BS Phone: 07545 826507 Email: scott.perham@gmail.com Perham Expires March 18, 2017 [Page 6]