Draft: draft-irtf-t2trg-rest-iot

Commentary: Currently work in progress 
  's comment refers to the strong reduction of the " Thing " definition . I tried to get some useful information back , but kept the started discussion on " Thingness " out . 
 The term " affordance " was actually never used in the text ( only in terminology ) . I more information that puts hypermedia controls in context to affordances . 
 We might have a bit of a problem in Section 5 , as the work on CoRAL stalled with  not being active on it anymore ... Might this change now after the change on your side I heard about ?
Different protocols can be used with RESTful systems, but at the time
of writing the most common protocols are HTTP RFC7230 and CoAP
RFC7252.  Since RESTful APIs are often simple and lightweight, they
are a good fit for various IoT applications.  The goal of this
document is to give basic guidance for designing RESTful systems and
APIs for IoT applications and give pointers for more information.
This section explains some of the common terminology that is used in
the context of RESTful design for IoT systems.  For terminology of
constrained nodes and networks, see RFC7228.  Terminology on modeling
of Things and their Affordances (Properties, Actions, and Events) was
taken from I-D.ietf-asdf-sdf.
An affordance that can potentially be used to perform a named
operation on an Object.
Different protocols can be used with RESTful systems, but at the time
of writing the most common protocols are HTTP RFC7230 and CoAP
RFC7252.  Since RESTful APIs are often lightweight and enable loose
coupling of system components, they are a good fit for various
Internet of Things (IoT) applications, which in general aim at
interconnecting the physical world with the virtual world.  The goal
of this document is to give basic guidance for designing RESTful
systems and APIs for IoT applications and give pointers for more
information.
This section explains selected terminology that is commonly used in
the context of RESTful design for IoT systems.  For terminology of
constrained nodes and networks, see RFC7228.  Terminology on modeling
of Things and their affordances (Properties, Actions, and Events) was
taken from I-D.ietf-asdf-sdf.
An affordance that can potentially be used to perform a named
operation on a Thing.
A representation sent as a response by a server that does not
represent resource state, but the result of the interaction with
the originally addressed resource.
A node that sends requests to servers and receives responses.  In
RESTful IoT systems it's common for nodes to have more than one
role (e.g., both server and client; see sec-architecture).
To use an access mechanism (e.g., HTTP or CoAP) to perform an
action on a URI's resource.
A URI that can be dereferenced, i.e., an action can be performed
on the identified resource.  Not all HTTP or CoAP URIs are
dereferencable, e.g., when the target resource does not exist.
An affordance that can potentially be used to obtain information
about what happened to an Object.
A hypermedia control that enables a client to change the state of
a resource or to construct a query locally.
A node that sends requests to servers and receives responses; it
therefore has the initiative to interact.  In RESTful IoT systems
it is common for nodes to have more than one role (i.e., to be
both server and client; see sec-architecture).
A string that carries the media type plus potential parameters for
the representation format such as "text/plain;charset=UTF-8".
To use an access mechanism (e.g., HTTP or CoAP) to interact with
the resource of a URI.
A URI that can be dereferenced, i.e., interaction with the
identified resource is possible.  Not all HTTP or CoAP URIs are
dereferencable, e.g., when the target resource does not exist.
An affordance that can potentially be used to (recurrently) obtain
information about what happened to a Thing, e.g., through server
push.
A hypermedia control that enables a client to construct more
complex requests, e.g., to change the state of a resource or
perform specific queries.
A component, such as a link or a form, embedded in a
representation that identifies a resource for future hypermedia
interactions.  If the client engages in an interaction with the
identified resource, the result may be a change to resource state
and/or client state.
Information provided by a server on how to use its RESTful API;
usually a URI and instructions on how to dereference it for a
specific interaction.  Hypermedia Controls are the serialized/
encoded affordances of hypermedia systems.
A string such as "text/html" or "application/json" that is used to
label representations so that it is known how the representation
should be interpreted and how it is encoded.
An IANA-registered string such as "text/html" or "application/
json" that is used to label representations so that it is known
how the representation should be interpreted and how it is
encoded.
A content negotiation mechanism where the server selects a
representation based on the expressed preference of the client.
For example, an IoT application could send a request to a sensor
with preferred media type "application/senml+json".
An affordance that can potentially be used to read, write, and/or
observe state on an Object.
A content negotiation mechanism where the server selects a
representation based on the expressed preference of the client.
For example, an IoT application could send a request that prefers
to accept the media type "application/senml+json".
An affordance that can potentially be used to read, write, and/or
observe state on a Thing.
A serialization that represents the current or intended state of a
resource and that can be transferred between clients and servers.
REST requires representations to be self-describing, meaning that
there must be metadata that allows peers to understand which
representation format is used.  Depending on the protocol needs
and capabilities, there can be additional metadata that is
transmitted along with the representation.
A serialization that represents the current or intended state of a
resource and that can be transferred between client and server.
REST requires representations to be self-describing, meaning that
there must be metadata that allows peers to understand which
representation format is used.  Depending on the protocol needs
and capabilities, there can be additional metadata that is
transmitted along with the representation.
A model of a resource's possible states that is represented in a
supported representation type, typically a media type.  Resources
can change state because of REST interactions with them, or they
can change state for reasons outside of the REST model.
A model of the possible states of a resource that is expressed in
supported representation formats.  Resources can change state
because of REST interactions with them, or they can change state
for reasons outside of the REST model, e.g., business logic
implemented on the server side such as sampling a sensor.
A node that listens for requests, performs the requested operation
and sends responses back to the clients.
A physical device that is also made available in the Internet of
Things.  The term is used here for Things that are notable for
their interaction with the physical world beyond interaction with
humans; a temperature sensor or a light might be a Thing, but a
router that employs both temperature sensors and indicator lights
might exhibit less Thingness, as the effects of its functioning
are mostly on the digital side.
In particular in IoT domain, protocols above transport layer that
are used to transfer data objects and provide semantics for
operations on the data.
A node that listens for requests, performs the requested
operation, and sends responses back to the clients.  In RESTful
IoT systems it is common for nodes to have more than one role
(i.e., to be both server and client; see sec-architecture).
A physical item that is made available in the Internet of Things,
thereby enabling digital interaction with the physical world for
humans, services, and/or other Things.
In particular in the IoT domain, protocols above the transport
layer that are used to transfer data objects and provide semantics
for operations on the data.
measurement or door lock control capability) as resources.  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 data, in client role.
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.
When designing a RESTful system, the primary effort goes into
modeling the state of the distributed application and assigning it to
the different components (i.e., clients and servers).  How clients
can navigate through the resources and modify state to achieve their
goals is defined through hypermedia controls, that is, links and
forms.  Hypermedia controls span a kind of a state machine where the
nodes are resources and the transitions are links or forms.  Clients
run this state machine (i.e., the application) by retrieving
representations, processing the data, and following the included
hypermedia controls.  In REST, remote state is changed by submitting
forms.  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.
Client state encompasses the current state of the described state
machine and the possible next transitions derived from the hypermedia
controls within the currently processed representation (see sec-
terms).  Furthermore, clients can have part of the state of the
distributed application in local variables.
It is important to distinguish between "client state" and "resource
state" and keep them separate.  Following the Stateless constraint,
the client state must be kept only on clients.  That is, there is no
establishment of shared information about past and future
interactions between client and server (usually called a session).
On the one hand, this makes requests a bit more verbose since every
request must contain all the information necessary to process it.  On
the other hand, this makes servers efficient and scalable, since they
do not have to keep any state about their clients.  Requests can
easily be distributed over multiple worker threads or server
instances.  For IoT systems, this constraint lowers the memory
requirements for server implementations, which is particularly
important for constrained servers (e.g., sensor nodes) and servers
serving large amount of clients (e.g., Resource Directory).
An important part of RESTful API design is to model the system as a
set of resources whose state can be retrieved and/or modified and
where resources can be potentially also created and/or deleted.
Uniform Resource Identifiers (URIs) are used to indicate a resource
for interaction, to reference a resource from another resource, to
advertise or bookmark a resource, or to index a resource by search
engines.
When designing a RESTful system, the primary effort goes into
modeling the application as distributed state and assigning it to the
different components (i.e., clients and servers).  The secondary
effort is then selecting or designing the necessary representation
formats to exchange information and enable interaction between the
components through resources.
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 a 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.
Client state encompasses the current state of the described state
machine and the possible next transitions derived from the hypermedia
controls within the currently processed representation.  Furthermore,
clients can have part of the state of the distributed application in
local variables.
In the design, it is important to distinguish between "client state"
and "resource state", and keep them separate.  Following the
Stateless constraint, the client state must be kept only on clients.
That is, there is no establishment of shared information about past
and future interactions between client and server (usually called a
session).  On the one hand, this makes requests a bit more verbose
since every request must contain all the information necessary to
process it.  On the other hand, this makes servers efficient and
scalable, since they do not have to keep any state about their
clients.  Requests can easily be distributed over multiple worker
threads or server instances (cf. load balancing).  For IoT systems,
this constraint lowers the memory requirements for server
implementations, which is particularly important for constrained
servers (e.g., sensor nodes) and servers serving large amount of
clients (e.g., Resource Directory).
An important aspect of RESTful API design is to model the system as a
set of resources, which potentially can be created and/or deleted
dynamically and whose state can be retrieved and/or modified.
Uniform Resource Identifiers (URIs) are used to indicate resources
for interaction, to reference a resource from another resource, to
advertise or bookmark a resource, or to index a resource by search
engines.
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 "http"
scheme.  A host name (e.g., a fully qualified domain name) or an IP
address, potentially followed by a transport layer port number, are
usually used in the authority component for the "http" and "coap"
schemes.  The path and query contain data to identify a resource
within the scope of the URI's scheme and naming authority.  The
fragment allows to refer 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.
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 to refer 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 HTTP protocol for "http" and
"https", and with the CoAP protocol 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 rest 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 dereferencable, e.g., the "urn" scheme can be used to
construct unique names in registered namespaces.  In particular the
"urn:dev" I-D.ietf-core-dev-urn details multiple ways for generating
and representing endpoint identifiers of IoT devices.
The query parameters can be used to parametrize 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 commonly used.  Whether the
order of the query parameters matters in URIs is unspecified and they
can be re-ordered e.g., by proxies.  Therefore applications should
not rely on their order; see Section 3.3 of RFC6943 for more details.
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.
Some schemes are for URIs with main purpose as identifiers, and hence
are not dereferencable, 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 parametrize 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 and
they can be re-ordered, for instance by proxies.  Therefore
applications should not rely on their order; see Section 3.3 of
RFC6943 for more details.
Clients can retrieve the resource state from an origin server or
manipulate resource state on the origin server by transferring
resource representations.  Resource representations have a content-
type (media-type, optionally with parameters) that tells how the
representation should be interpreted by identifying the
representation format used.
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.
The terms "media-type", "content-type", 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.
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.
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.
Hypermedia-driven applications take advantage of hypermedia controls,
i.e., links and forms, embedded in the resource representations.  A
hypermedia client is a client that is capable of processing these
hypermedia controls.  Hypermedia links can be used to give additional
information about a resource representation (e.g., the source URI of
the representation) or pointing to other resources.  The forms can be
used to describe the structure of the data that can be sent (e.g.,
with a POST or PUT method) to a server, or how a data retrieval
(e.g., GET) request for a resource should be formed.  In a
hypermedia-driven application the client interacts with the server
using only the hypermedia controls, instead of selecting methods and/
or constructing URIs based on out-of-band information, such as API
documentation.  The Constrained RESTful Application Language (CoRAL)
I-D.ietf-core-coral provides a hypermedia-format that is suitable for
constrained IoT environments.
Hypermedia-driven applications take advantage of hypermedia controls,
i.e., links and forms, which are embedded in representations or
response message headers.  A hypermedia client is a client that is
capable of processing these hypermedia controls.  Hypermedia links
can be used to give additional information about a resource
representation (e.g., the source URI of the representation) or
pointing to other resources.  The forms can be used to describe the
structure of the data that can be sent (e.g., with a POST or PUT
method) to a server, or how a data retrieval (e.g., GET) request for
a resource should be formed.  In a hypermedia-driven application the
client interacts with the server using only the hypermedia controls,
instead of selecting methods and/or constructing URIs based on out-
of-band information, such as API documentation.  The Constrained
RESTful Application Language (CoRAL) I-D.ietf-core-coral provides a
hypermedia-format that is suitable for constrained IoT environments.