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,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, DOI 10.17487/
RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>.
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]