CoRE C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track October 19, 2015 Expires: April 21, 2016 CoAP FETCH Method draft-bormann-core-coap-fetch-00 Abstract Similar to HTTP, the existing Constrained Application Protocol (CoAP) GET method only allows the specification of a URI and request parameters in CoAP options, not the transfer of a request payload detailing the request. This leads to some applications to using POST where actually a cacheable, idempotent, safe request is desired. The present proposal adds a new CoAP method, FETCH, to perform the equivalent of a GET with a request body. This specification is inspired by I-D.snell-search-method, which updates the definition and semantics of the HTTP SEARCH request method previously defined by RFC5323. However, there is no intention to limit FETCH to search-type operations, and the resulting properties may not be the same as those of HTTP SEARCH. For now, we therefore prefer to discuss the proposal under a different name, for which we have chosen the GET synonym FETCH. Status of This Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on April 21, 2016. Bormann Expires April 21, 2016 [Page 1] Internet-Draft CoAP FETCH Method October 2015 Copyright Notice Copyright (c) 2015 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. FETCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. The Content-Format Option . . . . . . . . . . . . . . . . 4 2.2. Working with Observe . . . . . . . . . . . . . . . . . . 4 2.3. Working with Block . . . . . . . . . . . . . . . . . . . 5 2.4. Discussion . . . . . . . . . . . . . . . . . . . . . . . 5 3. Security Considerations . . . . . . . . . . . . . . . . . . . 5 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 6.1. Normative References . . . . . . . . . . . . . . . . . . 5 6.2. Informative References . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction The CoAP GET method [RFC7252] is used to obtain the representation of a resource, where the resource is specified by a URI and additional request parameters can additionally shape the representation. This has been modelled after the HTTP GET operation and the REST model in general. In HTTP, a resource is often used to search for information, and existing systems varyingly use the HTTP GET and POST methods to perform a search. Often a POST method is used solely to enable supplying a larger set of parameters to the search than can be comfortably transferred in the URI with a GET request. [I-D.snell-search-method] proposes a SEARCH method that is similar to GET in most properties but enables sending a request body as with POST. A major problem with GET is that the information that controls the request needs to be bundled up in some unspecified way into the URI. Bormann Expires April 21, 2016 [Page 2] Internet-Draft CoAP FETCH Method October 2015 Using the request body for this information has a number of advantages: o The client can specify a media type (and a content encoding), enabling the server to unambiguously interpret the request parameters in the context of that media type. Also, the request body is not limited by the character set limitations of URIs, enabling a more natural (and more efficient) representation of certain domain-specific parameters. o The request parameters are not limited by the maximum size of the URI. In HTTP, that is a problem as the practical limit for this size varies. In CoAP, another problem is that the block-wise transfer is not available for transferring large URI options in multiple rounds. As an alternative to using GET, many implementations make use of the POST method to perform extended requests, even if they are semantically idempotent, safe, and even cacheable, to be able to pass along the input parameters within the request payload as opposed to using the request URI. The FETCH method provides a solution that spans the gap between the use of GET and POST. As with POST, the input to the FETCH operation is passed along within the payload of the request rather than as part of the request URI. Unlike POST, however the semantics of the FETCH method are more specifically defined. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. FETCH The CoAP FETCH method is used to obtain a representation of a resource, giving a number of request parameters. Unlike the CoAP GET method, which requests that a server return a representation of the resource identified by the effective request URI (as defined by [RFC7252]), the FETCH method is used by a client to ask the server to produce a representation based on the request parameters (described by the request options and payload) based on the resource specified by the effective request URI. The payload returned in response to a FETCH cannot be assumed to be a complete representation of the resource identified by the effective request URI. The body of the request defines the request parameters. Implementations MAY use a request body of any content type with the Bormann Expires April 21, 2016 [Page 3] Internet-Draft CoAP FETCH Method October 2015 FETCH method; it is outside the scope of this document how information about admissible content types is obtained by the client (although we can hint that form relations ([I-D.hartke-core-apps]) might be the preferred way). FETCH requests are both safe and idempotent with regards to the resource identified by the request URI. That is, the performance of a fetch is not expected to alter the state of the targeted resource. (However, while processing a search request, a server can be expected to allocate computing and memory resources or even create additional server resources through which the response to the search can be retrieved.) A successful response to a FETCH request is expected to provide some indication as to the final disposition of the requested operation. If the response includes a body payload, the payload is expected to describe the results of the FETCH operation. Depending on the response code as defined by [RFC7252] the response to a FETCH request is cacheable; the request payload is part of the cache key. Specifically, 2.05 "Content" response codes, the responses for which are cacheable, are a usual way to respond to a FETCH request. (Note that this aspect differs markedly from [I-D.snell-search-method].) (Note also that caches that cannot use the request payload as part of the request key will not be able to cache responses to FETCH requests at all.) The Max-Age option in the response has equivalent semantics to its use in a GET. The semantics of the FETCH method change to a "conditional FETCH" if the request message includes an If-Match, or If-None-Match option ([RFC7252]). A conditional FETCH requests that the query be performed only under the circumstances described by the conditional option(s). It is important to note, however, that such conditions are evaluated against the state of the target resource itself as opposed to the results of the FETCH operation. [[This needs some additional text on what an ETag on a FETCH result means.]] 2.1. The Content-Format Option A FETCH request MUST include a Content-Format option to specify the media type and content encoding of the request body. 2.2. Working with Observe The Observe option [RFC7641] can be used with a FETCH request as it can be used with a GET request. Bormann Expires April 21, 2016 [Page 4] Internet-Draft CoAP FETCH Method October 2015 2.3. Working with Block The Block1 option [I-D.ietf-core-block] can be used with a FETCH request as it would be used with a POST request; the Block2 option can then be used as with GET or POST. 2.4. Discussion One property of FETCH that may be non-obvious is that a FETCH request cannot be generated from a link alone, but also needs a way to generate the request payload. Again, form relations ([I-D.hartke-core-apps]) may be able to fill parts of this gap. 3. Security Considerations The FETCH method is subject to the same general security considerations as all CoAP methods as described in [RFC7252]. 4. IANA Considerations IANA is requested to add an entry to the sub-registry "CoAP Method Codes": | Code | Name | Reference | +------+--------+-----------+ | 0.07 | FETCH | [RFCthis] | The FETCH method is idempotent and safe, and it returns the same response codes that GET can return, plus 4.15 "Unsupported Content- Format" with the same semantics as with POST. 5. Acknowledgements Most of the text in this I-D was stolen, e.g. from [I-D.snell-search-method] or from [I-D.vanderstok-core-patch]. Thank you! Klaus Hartke found a number of problems while quickly checking an earlier version of this document. 6. References 6.1. Normative References [I-D.ietf-core-block] Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", draft-ietf-core-block-18 (work in progress), September 2015. Bormann Expires April 21, 2016 [Page 5] Internet-Draft CoAP FETCH Method October 2015 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ RFC7252, June 2014, . [RFC7641] Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ RFC7641, September 2015, . 6.2. Informative References [I-D.hartke-core-apps] Hartke, K., "CoRE Application Descriptions", draft-hartke- core-apps-02 (work in progress), August 2015. [I-D.snell-search-method] Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH Method", draft-snell-search-method-00 (work in progress), April 2015. [I-D.vanderstok-core-patch] Stok, P. and A. Sehgal, "Patch Method for Constrained Application Protocol (CoAP)", draft-vanderstok-core- patch-02 (work in progress), October 2015. Author's Address Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Bormann Expires April 21, 2016 [Page 6]