]> Ericsson

Finland jaime@iki.fi

Universität Bremen TZI

Postfach 330440 D-28359 Bremen Germany +49-421-218-63921 cabo@tzi.org

Web and Internet Transport CoRE Working Group This document defines the 2.06 (No Content) response code for the Constrained Application Protocol (CoAP). The code indicates that the target resource exists but has no current representation to transfer. It allows a client to retrieve or observe a resource before that resource has any content, without the server signaling an error. This document updates RFC 7641 to allow 2.06 (No Content) notifications, and specifies how cross-proxies map the code to and from the HTTP 204 (No Content) status code. About This Document Status information for this document may be found at . Discussion of this document takes place on the core Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction CoAP defines a set of success response codes in . A GET request that succeeds returns 2.05 (Content) with a representation of the target resource. A GET request on a resource that does not exist returns 4.04 (Not Found). CoAP has no code for the case in between: the resource exists, but no representation of it is available yet, or the last representation has been removed or has expired. This case occurs in several CoRE applications. In the publish-subscribe architecture of , a topic-data resource has no content between topic creation and the first publication. Because a GET or Observe registration on such a resource cannot succeed, that specification introduces a "half created" topic state, answers requests in that state with 4.04 (Not Found), and provides an "initialize" property so that a creator can install placeholder data. A client then has to infer the topic state from which operations fail. A sensor whose last reading has expired, or a resource whose value has been cleared, have the same gap. Servers fill the gap today in one of three ways, each with a drawback. A 4.04 (Not Found) response terminates an Observe registration (), so a subscriber cannot register interest until data exists and has to poll instead. A 2.05 (Content) response with an empty payload is ambiguous: a zero-length payload is a valid representation in some Content-Formats (for instance, an empty text/plain string), so the client cannot tell "the value is empty" from "there is no value". A 5.03 (Service Unavailable) response signals a server-side failure when no failure has occurred. HTTP addresses this case with 204 (No Content) (): the server has fulfilled the request and there is no content to send. The HTTP-to-CoAP mapping in maps HTTP 204 only to 2.02 (Deleted) and 2.04 (Changed), which are not used in response to GET. This document defines 2.06 (No Content) for CoAP, specifies its use with GET, FETCH, and Observe, and gives the mapping to and from HTTP 204 (No Content). It does not change the semantics of any existing response code, and it does not define how a resource comes to have no representation; that is up to the application.

Terminology 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 () () when, and only when, they appear in all capitals, as shown here. This document uses the terms "resource", "representation", "origin server", "proxy", and "cross-proxy" as defined in , and "observer", "registration", and "notification" as defined in .

The 2.06 (No Content) Response Code

Semantics The 2.06 (No Content) response code indicates that the server has fulfilled the request, that the target resource exists, and that the resource has no current representation to transfer in the response. A server MUST NOT include a payload in a 2.06 (No Content) response. A server MUST NOT include a Content-Format Option or an ETag Option in a 2.06 (No Content) response, since there is no representation to describe or tag. A client that receives 2.06 (No Content) learns that the resource exists. If the client holds a representation of the resource from an earlier response, it MUST NOT treat that representation as the current state of the resource.

Applicable Methods A server uses 2.06 (No Content) in response to GET and FETCH requests. For FETCH, the code indicates that the target resource exists and the selected part of it has no representation. A server MUST NOT use 2.06 (No Content) in response to PUT, POST, PATCH, iPATCH, or DELETE requests. Those methods already have success codes that carry no payload: 2.04 (Changed) and 2.02 (Deleted).

Distinction from 2.05 (Content) and 4.04 (Not Found) A 2.05 (Content) response with a zero-length payload carries a representation of length zero in the indicated Content-Format. A 2.06 (No Content) response carries no representation at all. A server that has an empty representation of a resource, such as the empty CBOR array or an empty string, returns it with 2.05 (Content). A server that has no representation returns 2.06 (No Content). A 4.04 (Not Found) response indicates that the server has no resource at the target URI. A server MUST NOT return 2.06 (No Content) for a URI at which no resource exists.

Caching A 2.06 (No Content) response is cacheable. Caches use the Max-Age Option to determine freshness (). A server SHOULD set Max-Age to the time after which it expects the resource may have a representation, if known. A cached 2.06 (No Content) response satisfies subsequent GET requests with the same cache key while it is fresh. A client MAY include ETag Options in a GET request on a resource that currently has no representation. Since none of the entity tags can match, the server responds with 2.06 (No Content).

Endpoints That Do Not Implement This Document An endpoint that does not implement this document handles 2.06 (No Content) by the rule of for an unrecognized Success class code: the request succeeded, without further details. Since a 2.06 response carries neither a payload nor a Content-Format Option, such a client observes what it observes on a 2.05 (Content) response with an empty payload and no Content-Format Option, which is one of the responses listed in . Receiving 2.06 therefore gives such a client the same information as the response it receives from a server that does not implement this document. A cache that does not implement this document does not store a 2.06 response, as requires for unrecognized Success class codes. A cache that does implement it stores the response per . An observer that does not implement this document remains registered on a 2.06 notification, since removes observers only on non-2.xx notifications, and treats the notification as an empty representation, as it would a 2.05 (Content) notification with an empty payload. For these reasons, a server that implements this document sends 2.06 (No Content) whenever applies, without regard to what it knows about the client. A server has no signal of the capabilities of the client, and when a proxy is in the path it does not see the client at all. Each alternative response () is worse for clients that implement this document and no better for clients that do not.

Use with Observe Observe is one consumer of 2.06 (No Content); the code itself is defined by independently of it. The following subsections specify how registrations and notifications use the code.

Registration A client registers interest in a resource that has no current representation by sending a GET request with an Observe Option set to 0. A server that supports this document and is willing to add the client to the list of observers responds with 2.06 (No Content) and includes an Observe Option. As with any 2.xx response that carries an Observe Option (), this confirms the registration.

Notifications states that a notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response code. This document adds 2.06 (No Content) to that list. When the resource of an observed registration gains a representation, the server sends a 2.05 (Content) notification as usual. When the resource loses its representation, for instance because the data was removed or has expired, the server sends a 2.06 (No Content) notification that includes an Observe Option. The client remains on the list of observers. On receipt, the client discards the previously notified representation, per . A 2.06 (No Content) notification follows the ordering rules of and the freshness rules of , using its Observe sequence number and Max-Age Option.

Content-Format Consistency requires the Content-Format of a 2.xx notification to be the same as the one used in the initial response. This requirement does not apply to 2.06 (No Content) notifications, which carry no Content-Format Option. If the initial response to a registration is 2.06 (No Content), the Content-Format of the first 2.05 (Content) notification determines the Content-Format for all subsequent 2.05 (Content) notifications of that registration. A client that needs a specific Content-Format SHOULD include an Accept Option in the registration request, so that the server can reject the registration with 4.06 (Not Acceptable) if it cannot produce that format.

Proxying and HTTP Mapping 2.06 (No Content) is an end-to-end response code. A CoAP-to-CoAP proxy forwards it unchanged and caches it per . A proxy that does not implement this document forwards a 2.06 (No Content) response like any other response and does not cache it (). A proxy that implements this document does not translate 2.06 for clients that might not recognize it: the response code is end-to-end, and the proxy has no better knowledge of the client than the origin server has (). defines no mapping for CoAP response codes absent from Table 2, so the behavior of an HTTP-to-CoAP cross-proxy that does not implement this document is implementation-specific. A CoAP-to-HTTP cross-proxy that does not implement this document maps HTTP 204 (No Content) in response to GET to 2.05 (Content) with an empty payload, per . An HTTP-to-CoAP cross-proxy that implements this document maps a CoAP 2.06 (No Content) response to an HTTP 204 (No Content) response, as if Table 2 in contained that row. The proxy translates Max-Age into HTTP freshness information as specified in . A CoAP-to-HTTP cross-proxy that implements this document () maps an HTTP 204 (No Content) response to a GET request into a CoAP 2.06 (No Content) response. For other methods, the existing mappings to 2.04 (Changed) and 2.02 (Deleted) apply.

Example: Publish-Subscribe Topics This section is informative. Messages are written in the CoAP Diagnostic Message Notation . The section shows how a publish-subscribe broker following could use 2.06 (No Content), assuming the broker creates the topic-data resource together with the topic. A subscriber reads the topic-data resource before any data has been published, then registers for notifications. Both requests succeed:

Reading a Topic with No Data

Subscribing to a Topic with No Data

A publisher then publishes the first value. Since the resource already exists, the broker returns 2.04 (Changed), and notifies the subscriber:

First Publication

Notification of the First Value

If the data later expires, the broker sends a 2.06 (No Content) notification. The subscriber stays registered and stops using the value of 23 Cel:

Notification That the Data Has Expired

With this code, the broker needs neither a separate "half created" state nor 4.04 (Not Found) responses on an existing topic, and subscribers can register at any time after the topic is created.

Security Considerations The security considerations of and apply. A 2.06 (No Content) response tells the client that a resource exists at the target URI, which a 4.04 (Not Found) response would not. A server that does not want to disclose the existence of a resource to an unauthorized client MUST respond with the same code it uses for nonexistent resources, as it would for any other request from that client. A 2.06 (No Content) response carries no payload and is smaller than the request that triggered it, so it does not add an amplification vector. Observe registrations accepted on resources with no representation keep observer state on the server for longer than registrations that would otherwise fail with 4.04 (Not Found). Servers apply the same limits on the number of observers that they apply to any other resource ().

IANA Considerations

CoAP Response Codes IANA is asked to add the following entry to the "CoAP Response Codes" registry within the "Constrained RESTful Environments (CoRE) Parameters" registry group, defined in : New CoAP Response Code

Code	Description	Reference
2.06	No Content	[RFC-XXXX]

The code 2.06 is a suggested value; it is unassigned in the registry, and the registration policy is IETF Review or IESG Approval. Note to RFC Editor: replace [RFC-XXXX] with this document's number.

References Normative References The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This memo defines application/multipart-core, an application-independent media type that can be used to combine representations of zero or more different media types (each with a Constrained Application Protocol (CoAP) Content-Format identifier) into a single representation, with minimal framing overhead. The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources. This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource. This document provides reference information for implementing a cross-protocol network proxy that performs translation from the HTTP protocol to the Constrained Application Protocol (CoAP). This will enable an HTTP client to access resources on a CoAP server through the proxy. This document describes how an HTTP request is mapped to a CoAP request and how a CoAP response is mapped back to an HTTP response. This includes guidelines for status code, URI, and media type mappings, as well as additional interworking advice. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Ericsson Dogtiger Labs Ericsson This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker. Ericsson Universität Bremen TZI This document defines a text notation for representing Constrained Application Protocol (CoAP) request/response exchanges in Internet- Drafts and RFCs. The notation balances human readability with mechanical validation: a reader can follow an exchange at a glance, and tooling can be built to parse the message structure and check each payload against its declared content format. The notation is application-layer by default, with message-layer detail added only where an example depends on it. It is a recommended convention for use in documents and with authoring tools such as kramdown-rfc, not a conformance target; it does not change CoAP or any on-the-wire encoding.

Design Alternatives This appendix records the alternatives considered. It is to be removed before publication.

2.05 (Content) with an empty payload:

Requires no new code, but cannot distinguish an empty representation from an absent one, and constrains the Content-Format of an Observe registration before any data exists.

4.04 (Not Found):

Conflates "no resource" with "no content", and terminates Observe registrations, so subscribers have to poll until data appears.

5.03 (Service Unavailable) with Max-Age:

Signals a temporary server failure; caches and clients treat it as an error, and it also terminates Observe registrations.

Placeholder representation:

An application-defined "empty" value, as with the "initialize" property of . Media types that have an empty, null, or undefined value can express the absence of content within the type. The meaning of that value is specific to each media type, existing media types cannot be retrofitted with one, and a generic client cannot recognize it.

Null media type:

A dedicated Content-Format that denotes the absence of content, sent in place of the requested representation. A response in this format conflicts with an Accept Option in the request. Introducing it would require changing the semantics of Accept to permit this format in any response or notification.

Multipart wrapper:

An application/multipart-core container that holds either a marker for the absence of content or the intended representation, so that one Content-Format covers both states. The outer format is fixed, so the client can no longer select the representation format with the Accept Option.

2.04 (Changed) in response to GET:

Used for this purpose in early revisions of . 2.04 (Changed) is defined for the result of PUT and POST, and reusing it for GET overloads its meaning.

Request option signaling support for 2.06:

Would follow the pattern by which 2.03 (Valid) and 2.31 (Continue) are only sent to clients that asked for them. Costs an option number and a byte per request to protect clients that already treat an unrecognized 2.xx as success (), and the fallback for requests without the option is the empty 2.05 (Content) response those clients receive without this document.

Acknowledgments Mike Bishop suggested a No Content success code during the AD review of . Michael Koster proposed a dedicated 2.06 code in issue 4 of the repository, including the requirement that a client stop using a stale value.