2. The Observe Option
The Observe Option has the following properties. Its meaning depends on whether it is included in a GET request or in a response.
| No. | C | U | N | R | Name | Format | Length | Default |
|---|---|---|---|---|---|---|---|---|
| 6 | x | - | Observe | uint | 0-3 B | (none) |
- C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable
Table 1: The Observe Option
When included in a GET request, the Observe Option extends the GET method so it does not only retrieve a current representation of the target resource, but also requests the server to add or remove an entry in the list of observers of the resource depending on the option value. The list entry consists of the client endpoint and the token specified by the client in the request. Possible values are:
-
0 (register) adds the entry to the list, if not present;
-
1 (deregister) removes the entry from the list, if present.
The Observe Option is not critical for processing the request. If the server is unwilling or unable to add a new entry to the list of observers, then the request falls back to a normal GET request and the response does not include the Observe Option.
The Observe Option is not part of the Cache-Key: a cacheable response obtained with an Observe Option in the request can be used to satisfy a request without an Observe Option, and vice versa. When a stored response with an Observe Option is used to satisfy a normal GET request, the option MUST be removed before the response is returned.
When included in a response, the Observe Option identifies the message as a notification. This implies that a matching entry exists in the list of observers and that the server will notify the client of changes to the resource state. The option value is a sequence number for reordering detection (see Sections 3.4 and 4.4).
The value of the Observe Option is encoded as an unsigned integer in network byte order using a variable number of bytes ('uint' option format); see Section 3.2 of RFC 7252 [RFC7252].