Draft: draft-keranen-t2trg-rest-iot

Commentary: The intro was a collection of independent sentences , each in a new paragraph . I am trying to improve the flow with more proper , fluent paragraphs . More editorial changes to come today . 
 No one awake ... so let 's have some progress and smooth out issues later ;)
The Representational State Transfer (REST) architectural style REST
is a set of guidelines and best practices for building distributed
hypermedia systems.
When REST principles are applied to the design of a system, the
result is often called RESTful and in particular an API following
these principles is called a RESTful API.
Different protocols can be used with RESTful systems, but at the time
of writing the most common protocols are HTTP RFC7230 and CoAP
RFC7252.
RESTful design facilitates many desirable features for a system, such
as good scaling properties.  RESTful APIs are also often simple and
lightweight and hence easy to use also with 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.
The Representational State Transfer (REST) architectural style REST
is a set of guidelines and best practices for building distributed
hypermedia systems.  At its core is a set of constraints, which when
fulfilled enable desirable properties for distributed software
systems such as scalability and modifiability.  When REST principles
are applied to the design of a system, the result is often called
RESTful and in particular an API following these principles is called
a RESTful API.
A hypermedia control that enables a client to change the state of
a resource.
A hypermedia control that enables a client to change the state of
a resource or to construct a query locally.
See "Reverse Proxy".
A reverse proxy that provides an interface to a non-RESTful system
such as legacy systems or alternative technologies such as
Bluetooth ATT/GATT.  See also "Reverse Proxy".
A method where multiple identical requests with that method lead
to 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
idenpotent 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.
A method where multiple identical requests with that method lead
to 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.
The components of a RESTful system are assigned one of two roles:
client or server.  User agents are always in the client role and have
the initiative to issue requests.  Intermediaries (such as forward
proxies and reverse proxies) 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.
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.
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.  This property
is enforced by the layered system constraint of REST, which says that
a client cannot see beyond the server it is connected to.
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.
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.
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).
Client state encompasses the control flow and the interactions
between the components (see sec-terms).  Following the statelessness
constraint, the client state must be kept only on clients.  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, 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
the IoT systems, it lowers the memory requirements for server
implementations, which is particularly important for constrained
servers and servers serving large amount of clients.
Resource state includes the more persistent data of an application
(i.e., independent of the application control flow).  This can be
static data such as device descriptions, persistent data such as
system configuration, but also dynamic data such as the current value
of a sensor on a thing.
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.
Resource representations have a media type that tells how the
representation should be interpreted.  Typical media types for IoT
systems include "text/plain" for simple UTF-8 text, "application/
octet-stream" for arbitrary binary data, "application/json" for JSON
RFC7159, "application/senml+json" I-D.ietf-core-senml for Sensor
Markup Language (SenML) formatted data, "application/cbor" for CBOR
RFC7049, "application/exi" for EXI W3C.REC-exi-20110310.  Full list
of registered internet media types is available at the IANA registry
IANA-media-types and media types registered for use with CoAP are
listed at CoAP Content-Formats IANA registry IANA-CoAP-media.
Client state encompasses the control flow and the interactions
between the components (see sec-terms).  Following the Stateless
constraint, the client state must be kept only on clients.  That is,
there is no establishment of shared information about 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 the IoT systems, it 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).
Resource state includes the more persistent data of an application
(i.e., independent of the client control flow and lifetime).  This
can be static data such as device descriptions, persistent data such
as system configuration, but also dynamic data such as the current
value of a sensor on a thing.
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.
Section 4.3 of RFC7231 defines the set of methods in HTTP;
Section 5.8 of RFC7252 defines the set of methods in CoAP.  The
following lists the most relevant methods and gives a short
explanation of their semantics.
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 media type
that tells how the representation should be interpreted by
identifying the representation format used.  Typical media types for
IoT systems include "text/plain" for simple UTF-8 text, "application/
octet-stream" for arbitrary binary data, "application/json" for the
JSON format RFC7159, "application/senml+json" I-D.ietf-core-senml for
Sensor Markup Language (SenML) formatted data, "application/cbor" for
CBOR RFC7049, and "application/exi" for EXI W3C.REC-exi-20110310.  A
full list of registered Internet Media Types is available at the IANA
registry IANA-media-types and numerical media types registered for
use with CoAP are listed at CoAP Content-Formats IANA registry IANA-
CoAP-media.
Section 4.3 of RFC7231 defines the set of methods in HTTP;
Section 5.8 of RFC7252 defines the set of methods in CoAP.  As part
of the Uniform Interface constraint, each method can have certain
properties that give guarantees to clients: Safe methods do not cause
any state change on the origin server when applied to a resource.
Idempotent methods can be applied multiple times to the same resource
while causing the same visible resource state as a single such
request.  The following lists the most relevant methods and gives a
short explanation of their semantics.
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 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 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.
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.
The following sub-sections briefly summarize the REST constraints and
explain how they enable the listed properties.
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.
This improves simplicity and visibility, as it is clear which
component started an interaction.  Furthermore, it improves
modifiability through a clear separation of concerns.
The Stateless constraint requires messages to be self-contained.
They must contain all the information to process it, independent from
previous messages.  This allows to strictly separate the client state
from the resource state.
This improves scalability and reliability, since servers or worker
threads can be replicated.  It also improves visibility because
message traces contain all the information to understand the logged
interactions.
Furthermore, the Stateless constraint enables caching.
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.  Less 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.
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 requests.  The mostly used
control for RESTful systems is Web Linking RFC5590.  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 different 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.
This constraint enforces that a client cannot see beyond the server
with which it is interacting.
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.
This principle enables origin servers to ship code to clients.
Code-on-Demand improves modifiability, since new features can be
deployed during runtime (e.g., support for a new representation
format).  It also improves performance, as the server can provide
code for local pre-processing before transferring the data.