Draft: draft-irtf-t2trg-rest-iot

Commentary: I did a full pass to get some progress . I recommend to get consensus in this branch and then to a squash commit on merge , assuming that we open new branches for the major issues .
An element of an interface offered for interaction, defining its
possible uses or making clear how it can or should be used.  The
term is used here for the digital interfaces of a Thing only; it
might also have physical affordances such as buttons, dials, and
displays.
An element of an interface offered for interaction, defining its
possible uses or making clear how it can or should be used.  The
term is used here for the digital interfaces of a Thing only; the
Thing might also have physical affordances such as buttons, dials,
and displays.
System component in both server and client role.  See "Forward
Proxy", "Gateway", and "Reverse Proxy".
An intermediary that appears as a server towards the client but
satisfies the requests by forwarding them to the actual server
(possibly via one or more other intermediaries).  A reverse proxy
is often used to encapsulate legacy services, to improve server
performance through caching, and to enable load balancing across
multiple machines.
An intermediary that appears as a server towards the client, but
satisfies the requests by making its own request toward the origin
server (possibly via one or more other intermediaries) and
replying accordingly.  A reverse proxy is often used to
encapsulate legacy services, to improve server performance through
caching, or to enable load balancing across multiple machines.
The components of a RESTful system are assigned one or both of two
roles: client or server.  Note that the terms "client" and "server"
refer only to the roles that the nodes assume for a particular
message exchange.  The same node might act as a client in some
communications and a server in others.  Classic user agents (e.g.,
Web browsers) are always in the client role and have the initiative
to issue requests.  Origin servers always have the server role and
govern over the resources they host.  Simple IoT devices, such as
sensors and actuators, are commonly acting as servers and exposing
their physical world interaction capabilities (e.g., temperature
measurement or door lock control capability) as resources.
Which resources exist and how they can be used is expressed by the
servers in so-called affordances, which is metadata that can be
included in responses (e.g., the initial response from a well-known
resource) or be made available out of band (e.g., through a W3C Thing
Description document W3C-TD from a directory).  In RESTful systems,
affordances are encoded as hypermedia controls of which exist two
types: links that allow to navigate between resources and forms that
enable clients to formulate more complex requests (e.g., to modify a
resource or perform a query).
A typical IoT system client can be a cloud service that retrieves
data from the sensors and commands the actuators based on the sensor
information.  Alternatively an IoT data storage system could work as
a server where IoT sensor devices send their data in client role.
Intermediaries (such as forward proxies, reverse proxies, and
gateways) implement both roles, but only forward requests to other
intermediaries or origin servers.  They can also translate requests
to different protocols, for instance, as CoAP-HTTP cross-proxies
RFC8075.
Reverse proxies are usually imposed by the origin server.  In
addition to the features of a forward proxy, they can also provide an
interface for non-RESTful services such as legacy systems or
alternative technologies such as Bluetooth ATT/GATT.  In this case,
reverse proxies are usually called gateways.  This property is
enabled by the Layered System constraint of REST, which says that a
client cannot see beyond the server it is connected to (i.e., it is
left unaware of the protocol/paradigm change).
Nodes in IoT systems often implement both roles.  Unlike
intermediaries, however, they can take the initiative as a client
(e.g., to register with a directory, such as CoRE Resource Directory
I-D.ietf-core-resource-directory, or to interact with another Thing)
and act as origin server at the same time (e.g., to serve sensor
values or provide an actuator interface).
Components of a RESTful system assume one of two roles when
interacting: client or server.  Classic user agents (e.g., Web
browsers) are always in the client role and have the initiative to
interact with other components.  Origin servers govern over the
resources they host and always have the server role, in which they
wait for requests.
Simple IoT devices, such as connected sensors and actuators, are
commonly acting as servers to expose their physical world interaction
capabilities (e.g., temperature measurement or door lock control
capability) as resources.  A typical example of an IoT system client
is a cloud service that retrieves data from the sensors and commands
the actuators based on the sensor information.  Alternatively an IoT
data storage system could work as a server where IoT sensor devices
send their data in client role.
Intermediaries implement both roles, as they receive requests in
server role and satisfy them by issuing their own requests in client
role.  They do not, however, have initiative to issue requests on
their own.  They often provide a cache to improve the overall system
performance or, in the case of IoT, shield constrained devices from
too many requests.  They can also translate requests to different
RESTful protocols, for instance, as CoAP-HTTP cross-proxies RFC8075.
A forward proxy is an intermediary seleceted by the user agent
because of local application or system configuration.  It then
forwards the request on behalf of the user agent, for instance, when
the user agent is restricted by firewall rules or otherwise lacks the
capability itself (e.g., a CoAP device contacting an HTTP origin
server).
A reverse proxy is usually imposed by the origin server to
transparently implement new features such as load balancing or
interfaces to non-RESTful services such as legacy systems or
alternative technologies such as Bluetooth ATT/GATT BTCorev5.3.  In
the latter case, reverse proxies are usually called gateways.
Because of the Layered System constraint of REST, which says that a
client cannot see beyond the server it is connected to, the user
agent is not and does not need to be aware of the changes introduced
through reverse proxies.
Components in IoT systems often implement both roles.  Unlike
intermediaries, however, they can take the initiative as a client
(e.g., to register with a directory, such as CoRE Resource Directory
RFC9176, or to interact with another IoT device) and act as origin
server at the same time (e.g., to serve sensor values or provide an
actuator interface).
How clients can navigate through the resource space and modify state
to achieve their goals is encoded in hypermedia controls, that is,
links and forms within the representations.  The concept behind
hypermedia controls is to provide machine-understandable
"affordances" HCI, which refer to the perceived and actual properties
of a Thing and determine how it could possibly be used.  A physical
door may have a door knob as affordance, indicating that the door can
be opened by twisting the knob; a keyhole may indicate that it can be
locked.  For Things in the IoT, these affordances may be serialized
as two hypermedia forms, which include semantic identifiers from a
controlled vocabulary (e.g., schema.org) and the instructions on how
to formulate the requests for opening and locking, respectively.
Overall, this allows to realize a Uniform Interface (see sec-uniform-
interface), which enables loose coupling between clients and servers.
Hypermedia controls span a kind of state machine where the nodes are
resources (or action results) and the transitions are links or forms.
Clients run this distributed state machine (i.e., the application) by
retrieving representations, processing the data, and following the
included links and/or submitting forms to modify remote state.  This
is usually done by retrieving the current state, modifying the state
on the client side, and transferring the new state to the server in
the form of new representations - rather than calling a service and
modifying the state on the server side.
Which resources exist and how they can be used is expressed by the
server in so-called affordances, a concept adopted in the field of
human-computer interaction HCI.  Affordances can be described in
responses (e.g., the initial response from a well-known resource) or
out of band (e.g., through a W3C Thing Description document W3C-TD
from a directory).  In RESTful systems, affordances are encoded as
hypermedia controls (links and forms): links allow to navigate
between resources and forms enable clients to formulate more complex
requests (e.g., to modify a resource or perform a query).
A physical door may have a door knob as affordance, indicating that
the door can be opened by twisting the knob; a keyhole may indicate
that it can be locked.  For Things in the IoT, these affordances may
be serialized as two hypermedia forms, which include semantic
identifiers from a controlled vocabulary (e.g., schema.org) and the
instructions on how to formulate the requests for opening and
locking, respectively.  Overall, this allows to realize a Uniform
Interface (see sec-uniform-interface), which enables loose coupling
between clients and servers.
Hypermedia controls span a kind of state machine, where the nodes are
resources or action results and the transitions are links or forms.
Clients run this distributed state machine (i.e., the application) by
retrieving representations, processing the data, and following the
included links and/or submitting forms to trigger the corresponding
transition.  This is usually done by retrieving the current state,
modifying the copy of the state on the client side, and transferring
the new state to the server in the form of new representations -
rather than calling a service and modifying the state on the server
side.
Resource state includes the more persistent data of an application
(i.e., independent of individual clients).  This can be static data
such as device descriptions, persistent data such as system
configurations, but also dynamic data such as the current value of a
sensor on a Thing.
Resource state includes the more persistent data of an application
(i.e., data that exists independent of individual clients).  This can
be static data such as device descriptions, persistent data such as
system configurations, but also dynamic data such as the current
value of a sensor on a Thing.
A URI is a sequence of characters that matches the syntax defined in
RFC3986.  It consists of a hierarchical sequence of five components:
scheme, authority, path, query, and fragment (from most significant
to least significant).  A scheme creates a namespace for resources
and defines how the following components identify a resource within
that namespace.  The authority identifies an entity that governs part
of the namespace, such as the server "www.example.org" in the "https"
scheme.  A hostname (e.g., a fully qualified domain name) or an IP
address literal, potentially followed by a transport layer port
number, are usually used for the authority component.  The path and
query contain data to identify a resource within the scope of the
scheme-dependent naming authority (i.e., "http://www.example.org/" is
a different authority than "https://www.example.org").  The fragment
allows referring to some portion of the resource, such as a Record in
a SenML Pack (Section 9 of RFC8428).  However, fragments are
processed only at client side and not sent on the wire.  RFC8820
provides more details on URI design and ownership with best current
practices for establishing URI structures, conventions, and formats.
For RESTful IoT applications, typical schemes include "https",
"coaps", "http", and "coap".  These refer to HTTP and CoAP, with and
without Transport Layer Security (TLS, RFC5246 for TLS 1.2 and
RFC8446 for TLS 1.3).  (CoAP uses Datagram TLS (DTLS) RFC6347, the
variant of TLS for UDP.)  These four schemes also provide means for
locating the resource; using the protocols HTTP for "http" and
"https" and CoAP for "coap" and "coaps".  If the scheme is different
for two URIs (e.g., "coap" vs. "coaps"), it is important to note that
even if the remainder of the URI is identical, these are two
different resources, in two distinct namespaces.
A URI is a sequence of characters that matches the syntax defined in
RFC3986.  It consists of a hierarchical sequence of five components:
scheme, authority, path, query, and fragement identifier (from most
significant to least significant), while not all components are
necessary to form a valid URI.  A scheme creates a namespace for
resources and defines how the following components identify a
resource within that namespace.  The authority identifies an entity
that governs part of the namespace, such as the server
"www.example.org" in the "https" scheme.  A hostname (e.g., a fully
qualified domain name) or an IP address literal, optionally followed
by a transport layer port number, are usually used for the authority
component.  The path and optional query contain data to identify a
resource within the scope of the scheme-dependent naming authority
(i.e., "http://www.example.org" is a different authority than
"https://www.example.org"); if no path is given, the root resource is
addressed.  The fragement identifier allows referring to some portion
of the resource, such as a Record in a SenML Pack (Section 9 of
RFC8428).  However, fragement identifiers are processed only at
client side and not sent on the wire.  RFC8820 provides more details
on URI design and ownership with best current practices for
establishing URI structures, conventions, and formats.
For RESTful IoT applications, typical schemes include "https",
"coaps", "http", and "coap".  These refer to HTTP and CoAP, with and
without Transport Layer Security (TLS, RFC5246 for TLS 1.2 and
RFC8446 for TLS 1.3).  (CoAP uses Datagram TLS (DTLS) RFC9147, the
variant of TLS for UDP.)  These four schemes also provide means for
locating the resource; using the protocols HTTP for "http" and
"https" and CoAP for "coap" and "coaps".  If the scheme is different
for two URIs (e.g., "coap" vs. "coaps"), it is important to note that
even if the remainder of the URI is identical, these are two
different resources, in two distinct namespaces.
Some schemes are for URIs with main purpose as identifiers, and hence
are not dereferenceable, e.g., the "urn" scheme can be used to
construct unique names in registered namespaces.  In particular the
"urn:dev" URI RFC9039 details multiple ways for generating and
representing endpoint identifiers of IoT devices.
Some schemes are for URIs with the main purpose as identifiers, and
hence are not dereferenceable, e.g., the "urn" scheme can be used to
construct unique names in registered namespaces.  In particular the
"urn:dev" URI RFC9039 details multiple ways for generating and
representing endpoint identifiers of IoT devices.
The query parameters can be used to parameterize the resource.  For
example, a GET request may use query parameters to request the server
to send only certain kind data of the resource (i.e., filtering the
response).  Query parameters in PUT and POST requests do not have
such established semantics and are not used consistently.  Whether
the order of the query parameters matters in URIs is unspecified;
they can be re-ordered, for instance by proxies.  Therefore,
applications should not rely on their order; see Section 3.3.4 of
RFC6943 for more details.
Due to the relatively complex processing rules and text
representation format, URI handling can be difficult to implement
correctly in constrained devices.  Constrained Resource Identifiers
I-D.ietf-core-href provide a CBOR-based format of URIs that is better
suited also for resource constrained IoT devices.
The query parameters can be used to parameterize the resource.  For
example, a GET request may use query parameters to request the server
to send only certain kind data of the resource (i.e., filtering the
response).  Query parameters in PUT and POST requests do not have
such established semantics and are not used consistently.  Whether
the order of the query parameters matters in URIs is up to the server
implementation; they might even be re-ordered, for instance by
intermediaries.  Therefore, applications should not rely on their
order; see Section 3.3.4 of RFC6943 for more details.
Due to the relatively complex processing rules and text
representation format, URI handling can be difficult to implement
correctly in constrained devices.  Constrained Resource Identifiers
I-D.ietf-core-href provide a CBOR-based format of URIs that is better
suited for resource constrained devices.
A full list of registered Internet Media Types is available at the
IANA registry IANA-media-types and numerical identifiers for media
types, parameters, and content codings registered for use with CoAP
are listed at CoAP Content-Formats IANA registry IANA-CoAP-media.
A full list of registered Internet Media Types is available at the
IANA registry IANA-media-types.  Numerical identifiers for media
types, parameters, and content codings registered for use with CoAP
are listed at CoAP Content-Formats IANA registry IANA-CoAP-media.
The terms "media type", "content type" (media type plus potential
parameters), and "content format" (short identifier of content type
and content coding, abbreviated for historical reasons "ct") are
often used when referring to representation formats used with CoAP.
The differences between these terms are discussed in more detail in
I-D.bormann-core-media-content-type-format.
The terms "media type", "content type" (media type plus potential
parameters), and "content format" (short identifier of content type
and content coding, abbreviated for historical reasons "ct") are
often used when referring to representation formats used with CoAP.
The differences between these terms are discussed in more detail in
Section 2 of RFC9193.
Idempotent methods can be applied multiple times to the same resource
while causing the same visible resource state as a single such
request.  For example, the PUT method replaces the state of a
resource with a new state; replacing the state multiple times with
the same new state still results in the same state for the resource.
However, the response from the server can be different when the same
idempotent method is used multiple times.  For example when DELETE is
used twice on an existing resource, the first request would remove
the association and return success acknowledgement whereas the second
request would likely result in error response due to non-existing
resource.
Idempotent methods can be applied multiple times to the same resource
while causing the same eventual resource state as a single such
request (unless something else caused the resource state to change).
For example, the PUT method replaces the state of a resource with a
new state; replacing the state multiple times with the same new state
still results in the same state for the resource.  However, responses
from the server can be different when the same idempotent method is
used multiple times.  For example when DELETE is used twice on an
existing resource, the first request would remove the association and
return a success acknowledgement, whereas the second request would
likely result in an error response due to non-existing resource (note
that neither response is a representation of the resource).
The fundamental difference between the GET and FETCH methods is that
the request parameters are included as the payload of a FETCH
request, while in a GET request they're typically part of the query
string of the request URI.
The fundamental difference between the GET and FETCH methods is that
the request parameters are included as the payload of a FETCH
request, while in a GET request they are typically part of the query
string of the request URI.
Section 6 of RFC7231 defines a set of Status Codes in HTTP that are
used by application to indicate whether a request was understood and
satisfied, and how to interpret the answer.  Similarly, Section 5.9
of RFC7252 defines the set of Response Codes in CoAP.
The status codes consist of three digits (e.g., "404" with HTTP or
"4.04" with CoAP) where the first digit expresses the class of the
code.  Implementations do not need to understand all status codes,
but the class of the code must be understood.  Codes starting with 1
are informational; the request was received and being processed.
Codes starting with 2 indicate a successful request.  Codes starting
with 3 indicate redirection; further action is needed to complete the
request.  Codes stating with 4 and 5 indicate errors.  The codes
starting with 4 mean client error (e.g., bad syntax in the request)
whereas codes starting with 5 mean server error; there was no
apparent problem with the request, but server was not able to fulfill
the request.
Section 6 of RFC7231 defines a set of Status Codes in HTTP that are
assigned by the server to indicate whether a request was understood
and satisfied, and how to interpret the answer.  Similarly,
Section 5.9 of RFC7252 defines the set of Response Codes in CoAP.
The status codes consist of three digits (e.g., "404" with HTTP or
"4.04" with CoAP) where the first digit expresses the class of the
code.  Implementations do not need to understand all status codes,
but the class of the code must be understood.  Codes starting with 1
are informational; the request was received and being processed (not
available in CoAP).  Codes starting with 2 indicate a successful
request.  Codes starting with 3 indicate redirection; further action
is needed to complete the request (not available in CoAP).  Codes
stating with 4 and 5 indicate errors.  The codes starting with 4 mean
client error (e.g., bad syntax in the request) whereas codes starting
with 5 mean server error; there was no apparent problem with the
request, but the server was not able to fulfill the request.
Responses may be stored in a cache to satisfy future, equivalent
requests.  HTTP and CoAP use two different patterns to decide what
responses are cacheable.  In HTTP, the cacheability of a response
depends on the request method (e.g., responses returned in reply to a
GET request are cacheable).  In CoAP, the cacheability of a response
depends on the response code (e.g., responses with code 2.04 are
cacheable).  This difference also leads to slightly different
semantics for the codes starting with 2; for example, CoAP does not
have a 2.00 response code whereas 200 ("OK") is commonly used with
HTTP.
Responses may be stored in a cache to satisfy future, equivalent
requests.  HTTP and CoAP use two different patterns to decide what
responses are cacheable.  In HTTP, the cacheability of a response
depends on the request method (e.g., responses returned in reply to a
GET request are cacheable).  In CoAP, the cacheability of a response
depends on the response code (e.g., responses with code 2.04 are
cacheable).  This difference also leads to slightly different codes
starting with 2; for example, CoAP does not have a 2.00 response code
whereas 200 ("OK") is commonly used with HTTP.
As explained in the Architecture section, RESTful system components
have clear roles in every interaction.  Clients have the initiative
to issue requests, intermediaries can only forward requests, and
servers respond requests, while origin servers are the ultimate
recipient of requests that intent to modify resource state.
As explained in the Architecture section, RESTful system components
have clear roles in every interaction.  Clients have the initiative
to issue requests, intermediaries can only forward requests, and
servers respond to requests, while origin servers are the ultimate
recipient of requests that intend to modify resource state.
This constraint requires responses to have implicit or explicit
cache-control metadata.  This enables clients and intermediary to
store responses and re-use them to locally answer future requests.
The cache-control metadata is necessary to decide whether the
information in the cached response is still fresh or stale and needs
to be discarded.
Cache improves performance, as less data needs to be transferred and
response times can be reduced significantly.  Needing fewer transfers
also improves scalability, as origin servers can be protected from
too many requests.  Local caches furthermore improve reliability,
since requests can be answered even if the origin server is
temporarily not available.
Caching usually only makes sense when the data is used by multiple
participants.  In IoT systems, however, it might make sense to cache
also individual data to protect constrained devices and networks from
frequent requests of data that does not change often.  Security often
hinders the ability to cache responses.  For IoT systems, object
security RFC8613 may be preferable over transport layer security, as
it enables intermediaries to cache responses while preserving
security.
This constraint requires responses to have implicit or explicit
cache-control metadata.  This enables clients and intermediaries to
store responses and re-use them to locally answer future requests.
The cache-control metadata is necessary to decide whether the
information in the cached response is still fresh or stale and needs
to be discarded.
A cache improves performance, as less data needs to be transferred
and response times can be reduced significantly.  Needing fewer
transfers also improves scalability, as origin servers can be
protected from too many requests.  Local caches furthermore improve
reliability, since requests can be answered even if the origin server
is temporarily not available.
Introducing additional components to perform caching only makes sense
when the data is used by multiple participants (otherwise client-side
caching would be enough).  In IoT systems, however, it might make
sense to cache also individual data to protect constrained devices
and networks from frequent requests of data that does not change
often.  Security often hinders the ability to cache responses.  For
IoT systems, object security RFC8613 may be preferable over transport
layer security, as it enables intermediaries to cache responses while
preserving security.
All RESTful APIs use the same, uniform interface independent of the
application.  This simple interaction model is enabled by exchanging
representations and modifying state locally, which simplifies the
interface between clients and servers to a small set of methods to
retrieve, update, and delete state - which applies to all
applications.
In contrast, in a service-oriented RPC approach, all required ways to
modify state need to be modeled explicitly in the interface resulting
in a large set of methods - which differs from application to
application.  Moreover, it is also likely that different parties come
up with different ways how to modify state, including the naming of
the procedures, while the state within an application is a bit easier
to agree on.
All RESTful APIs use the same, uniform interface independent of the
application.  This simple interaction model is enabled by exchanging
representations and modifying state locally, which simplifies the
interface between clients and servers to a small set of methods to
retrieve, update, and delete state.  This small set can apply to many
different applications.
In contrast, in a service-oriented RPC approach, state is modified
remotely, directly by the server, and only the instruction what to
modify is exchanged.  Also retrieving state for local use is usually
solved through specific instructions depending on the individual
information.  This requires to model all the necessary instructions
beforehand and assign them to named procedures.  This results in a
application-specific interface with a large set of methods/
procedures.  Moreover, it is also likely that different parties come
up with different ways how to modify state, including the naming of
the procedures.  Hence, even very similar applications are likely not
interoperable.
The concept of hypermedia controls is also known as HATEOAS:
Hypermedia As The Engine Of Application State.  The origin server
embeds controls for the interface into its representations and
thereby informs the client about possible next requests.  The most
used control for RESTful systems today is Web Linking RFC8288.
Hypermedia forms are more powerful controls that describe how to
construct more complex requests, including representations to modify
resource state.
While this is the most complex constraints (in particular the
hypermedia controls), it improves many key properties.  It improves
simplicity, as uniform interfaces are easier to understand.  The
self-descriptive messages improve visibility.  The limitation to a
known set of representation formats fosters portability.  Most of
all, however, this constraint is the key to modifiability, as
hypermedia-driven, uniform interfaces allow clients and servers to
evolve independently, and hence enable a system to evolve.
The concept of hypermedia controls is also known as HATEOAS:
Hypermedia As The Engine Of Application State HATEOAS.  The origin
server embeds controls for the interface into its representations and
thereby informs the client about possible next requests.  The most
used control for RESTful systems today is Web Linking RFC8288.
Hypermedia forms are more powerful controls that describe how to
construct more complex requests, including representations to modify
resource state.
While this is the most complex constraint (in particular the
hypermedia controls), it improves many key properties.  It improves
simplicity, as uniform interfaces are easier to understand.  The
self-descriptive messages improve visibility.  The limitation to a
known set of representation formats fosters portability.  Most of
all, however, this constraint is the key to modifiability, as
hypermedia-driven, uniform interfaces allow clients and servers to
evolve independently, and hence enable a system to evolve.
A layered system is easier to modify, as topology changes become
transparent.  Furthermore, this helps scalability, as intermediaries
such as load balancers can be introduced without changing the client
side.  The clean separation of concerns helps with simplicity.
IoT systems greatly benefit from this constraint, as it allows to
effectively shield constrained devices behind intermediaries and is
also the basis for gateways, which are used to integrate other (IoT)
ecosystems.
A layered system is easier to modify, as topology changes become
transparent (i.e., remain unnoticed by previous layers).  This in
turn helps scalability, as reverse proxies such as load balancers can
be introduced without changing the client side.  The clean separation
of concerns in layers helps with simplicity.
IoT systems greatly benefit from this constraint, as it allows to
effectively shield constrained devices behind intermediaries.  It is
also the basis for gateways, which are used to integrate other (IoT)
ecosystems.
As of today, code-on-demand has not been explored much in IoT
systems.  Aspects to consider are that either one or both nodes are
constrained and might not have the resources to host or dynamically
fetch and execute such code.  Moreover, the origin server often has
no understanding of the actual application a mashup client realizes.
Still, code-on-demand can be useful for small polyfills, e.g., to
decode payloads, and potentially other features in the future.
As of today, code-on-demand has not been explored much in IoT
systems.  Aspects to consider are that either one or both nodes are
constrained and might not have the resources to host or dynamically
fetch and execute such code.  Moreover, the origin server often has
no understanding of the actual application a mashup client realizes.
Still, code-on-demand can be useful for small polyfills POLYFILLS,
e.g., to decode payloads, and potentially other features in the
future.
A client begins interacting with an application through a GET request
on an entry point URI.  The entry point URI is the only URI a client
is expected to know before interacting with an application.  From
there, the client is expected to make all requests by following links
and submitting forms that are provided in previous responses.  The
entry point URI can be obtained, for example, by manual configuration
or some discovery process (e.g., DNS-SD RFC6763 or Resource Directory
I-D.ietf-core-resource-directory).  For Constrained RESTful
environments "/.well-known/core" relative URI is defined as a default
entry point for requesting the links hosted by servers with known or
discovered addresses RFC6690.
A client begins interacting with an application through a GET request
on an entry point URI.  The entry point URI is the only URI a client
is expected to know before interacting with an application.  From
there, the client is expected to make all requests by following links
and submitting forms that are provided in previous responses.  The
entry point URI can be obtained, for example, by manual configuration
or some discovery process (e.g., DNS-SD RFC6763 or Resource Directory
RFC9176).  For Constrained RESTful environments "/.well-known/core",
a relative URI is defined as a default entry point for requesting the
links hosted by servers with known or discovered addresses RFC6690.
Assuming self-describing representation formats (i.e., human-readable
with carefully chosen terms or processable by a formatting tool) and
a client supporting the URI scheme used, a good rule of thumb for a
good hypermedia-driven design is the following: A developer should
only need an entry point URI to drive the application.  All further
information how to navigate through the application (links) and how
to construct more complex requests (forms) are published by the
server(s).  There must be no need for additional, out-of-band
information (e.g., API specification).
Assuming self-describing representation formats (i.e., human-readable
with carefully chosen terms or processable by a formatting tool) and
a client supporting the URI scheme used, a good rule of thumb for a
good hypermedia-driven design is the following: A developer should
only need an entry point URI to drive the application.  All further
information how to navigate through the application (links) and how
to construct more complex requests (forms) are published by the
server(s).  There must be no need for additional, out-of-band
information (e.g., an API specification).
Certain kinds of design problems are often recurring in variety of
domains, and often re-usable design patterns can be applied to them.
Also, some interactions with a RESTful IoT system are straightforward
to design; a classic example of reading a temperature from a
thermometer device is almost always implemented as a GET request to a
resource that represents the current value of the thermometer.
However, certain interactions, for example data conversions or event
handling, do not have as straightforward and well established ways to
represent the logic with resources and REST methods.
Certain kinds of design problems are often recurring in a variety of
domains, and often re-usable design patterns can be applied to them.
Also, some interactions with a RESTful IoT system are straightforward
to design; a classic example of reading a temperature from a
thermometer device is almost always implemented as a GET request to a
resource that represents the current value of the thermometer.
However, certain interactions, for example data conversions or event
handling, do not have as straightforward and well established ways to
represent the logic with resources and REST methods.
Examples of the collection pattern in RESTful IoT systems are the
CoRE Resource Directory I-D.ietf-core-resource-directory, CoAP pub/
sub broker I-D.ietf-core-coap-pubsub, and resource discovery via
".well-known/core".  Collection+JSON CollectionJSON is an example of
a generic collection Media Type.
Examples of the collection pattern in RESTful IoT systems include the
CoRE Resource Directory RFC9176, CoAP pub/sub broker I-D.ietf-core-
coap-pubsub, and resource discovery via ".well-known/core".
Collection+JSON CollectionJSON is an example of a generic collection
Media Type.
Monitoring information would be modeled as state of the task
resource, and hence be retrievable as representation.  The result -
when available - can be embedded in the representation or given as a
link to another sub-resource.  Modifying tasks can be modeled with
forms that either update sub-resources via PUT or do a partial write
using PATCH or POST.  Canceling a task would be modeled with a form
that uses DELETE to remove the task resource.
Monitoring information would be modeled as state of the task
resource, and hence be retrievable as representation.  CoAP Observe
can help to be notified efficiently about completion or other changes
to this information.  The result - when available - can be embedded
in the representation or given as a link to another sub-resource.
Modifying tasks can be modeled with forms that either update sub-
resources via PUT or do a partial write using PATCH or POST.
Canceling a task would be modeled with a form that uses DELETE to
remove the task resource.
As mentioned in the previous sections, POST request are a good way to
model functionality that does not necessarily affect resource state.
When the input data for the conversion is small and the conversion
result is deterministic, however, it can be better to use a GET
request with the input data in the URI query part.  The query is
parameterizing the conversion resource, so that it acts like a look-
up table.  The benefit is that results can be cached also for HTTP
(where responses to POST are not cacheable).  In CoAP, cacheability
depends on the response code, so that also a response to a POST
request can be made cacheable through a 2.05 Content code.
As mentioned in the previous sections, POST requests are a good way
to model functionality that does not necessarily affect resource
state.  When the input data for the conversion is small and the
conversion result is deterministic, however, it can be better to use
a GET request with the input data in the URI query part.  The query
is parameterizing the conversion resource, so that it acts like a
look-up table.  The benefit is that results can be cached also for
HTTP (where responses to POST are not cacheable).  In CoAP,
cacheability depends on the response code, so that also a response to
a POST request can be made cacheable through a 2.05 Content code.
In event-centric paradigms such as pub/sub, events are usually
represented by an incoming message that might even be identical for
each occurrence.  Since the messages are queued, the receiver is
aware of each occurrence of the event and can react accordingly.  For
instance, in an event-centric system, ringing a doorbell would result
in a message being sent that represents the event that it was rung.
In event-centric paradigms such as Publish-Subscribe (pub/sub),
events are usually represented by an incoming message that might even
be identical for each occurrence.  Since the messages are queued, the
receiver is aware of each occurrence of the event and can react
accordingly.  For instance, in an event-centric system, ringing a
doorbell would result in a message being sent that represents the
event that it was rung.
as Observe only guarantees eventual consistency (see Section 1.3 of
RFC7641).
as Observe guarantees eventual consistency only (see Section 1.3 of
RFC7641).
For stand-alone event notifications, that is, where every single
notification contains an identifiable event that must not be lost,
observing resources is not a good fit.  A better strategy is to model
each event as a new resource, whose existence is notified through
change-of-state notifications of an index resource (cf.  Collection
pattern).  Large numbers of events will cause the notification to
grow large, as it needs to contain a large number of Web links.
Block-wise transfers RFC7959 can help here.  When the links are
ordered by freshness of the events, the first block can already
contain all links to new events.  Then, observers do not need to
retrieve the remaining blocks from the server, but only the
representations of the new event resources.
For stand-alone event notifications, that is, where every single
notification contains an identifiable event that must not be lost,
observing resources is not a good fit.  A better strategy is to model
each event as a new resource, whose existence is notified through
change-of-state notifications of an index resource I-D.bormann-t2trg-
stp.  Large numbers of events will cause the notification to grow
large, as it needs to contain a large number of Web links.  Block-
wise transfers RFC7959 or pagenation can help here.  When the links
are ordered by freshness of the events, the first block or page can
already contain all links to new events.  Then, observers do not need
to retrieve the remaining blocks or pages from the server, but only
the representations of the new event resources.