Draft: draft-ietf-core-pubsub

Commentary: address issues # 1,2,3,4,5 removed the list of representations on POST but kept POST to publish , may do subscriber queueing in a separate document 
 The URI template should be confirmed : 
 PR resolved this
A group of REST resources, as defined in this document, which
together implement the CoAP pubsub service.
A server node capable of receiving messages (publications) from
and sending messages to other nodes, and able to match
subscriptions and publications in order to route messages to the
right destinations.  The broker can also temporarily store
publications to satisfy future subscriptions.
A group of REST resources, as defined in this document, which
together implement the required features of this specification.
A server node capable of receiving messages (publications) from
and sending messages to other nodes, and able to match
subscriptions and publications in order to route messages to the
right destinations.  The broker can also temporarily store
publications to satisfy future subscriptions and pending
notifications.
arch-fig shows the architecture of a CoAP pubsub service.  CoAP
pubsub Clients interact with a CoAP pubsub Broker through the CoAP
pubsub API which is hosted by the Broker.  State information is
updated between the Clients and the Broker.  The CoAP pubsub Broker
performs a store-and-forward of state update representations between
certain CoAP pubsub Clients.  Clients Subscribe to topics upon which
representations are Published by other Clients, which are forwarded
by the Broker to the subscribing clients.  A CoAP pubsub Broker may
be used as a REST resource proxy, retaining the last published
representation to supply in response to Read requests from Clients.
arch-fig shows the architecture of a CoAP pubsub service.  CoAP
pubsub Clients interact with a CoAP pubsub Broker through the CoAP
pubsub REST API which is hosted by the Broker.  State information is
updated between the Clients and the Broker.  The CoAP pubsub Broker
performs a store-and-forward of state update representations between
certain CoAP pubsub Clients.  Clients Subscribe to topics upon which
representations are Published by other Clients, which are forwarded
by the Broker to the subscribing clients.  A CoAP pubsub Broker may
be used as a REST resource proxy, retaining the last published
representation to supply in response to Read requests from Clients.
A CoAP pubsub Broker is a CoAP Server that exposes an API for clients
to use to initiate publish-subscribe interactions.  Avoiding the need
for direct reachability between clients, the broker only needs to be
reachable from all clients.  The broker also needs to have sufficient
resources (storage, bandwidth, etc.) to host CoAP resource services,
and potentially buffer messages, on behalf of the clients.
A CoAP pubsub Client interacts with a CoAP pubsub Broker using the
CoAP pubsub API.  Clients initiate interactions with a CoAP pubsub
broker.  A data source (e.g., sensor clients) can publish state
updates to the broker and data sinks (e.g., actuator clients) can
read from or subscribe to state updates from the broker.  Application
clients can make use of both publish and subscribe in order to
exchange state updates with data sources and sinks.
A CoAP pubsub Broker is a CoAP Server that exposes a REST API for
clients to use to initiate publish-subscribe interactions.  Avoiding
the need for direct reachability between clients, the broker only
needs to be reachable from all clients.  The broker also needs to
have sufficient resources (storage, bandwidth, etc.) to host CoAP
resource services, and potentially buffer messages, on behalf of the
clients.
A CoAP pubsub Client interacts with a CoAP pubsub Broker using the
CoAP pubsub REST API defined in this document.  Clients initiate
interactions with a CoAP pubsub broker.  A data source (e.g., sensor
clients) can publish state updates to the broker and data sinks
(e.g., actuator clients) can read from or subscribe to state updates
from the broker.  Application clients can make use of both publish
and subscribe in order to exchange state updates with data sources
and data sinks.
This section defines the API exposed by a CoAP pubsub Broker to
pubsub Clients.  The examples throughout this section assume the use
of CoAP RFC7252.  A CoAP pubsub Broker implementing this
specification MUST support the DISCOVERY, CREATE, PUBLISH, SUBSCRIBE,
UNSUBSCRIBE, READ, and REMOVE operations defined in this section.
CoAP pubsub Clients discover CoAP pubsub Brokers by using CoAP Simple
Discovery or through a Resource Directory (RD) I-D.ietf-core-
resource-directory.  A CoAP pubsub Broker SHOULD indicate its
presence and availability on a network by exposing a link to its
pubsub API at its .well-known/core location RFC6690.  A CoAP pubsub
broker MAY register its pubsub API location with a Resource
Directory. discover-fig shows an example of a client discovering a
local pubsub API using CoAP Simple Discovery.  A broker wishing to
advertise the CoAP pubsub API for Simple Discovery or through a
Resource Directory MUST use the link relation rt=core.ps.  A broker
MAY advertise its supported content formats and other attributes in
the link to its pubsub API.
A CoAP pubsub Broker MAY offer a topic discovery API to enable
Clients to find topics of interest, either by topic name or by link
attributes which may be registered when the topic is created.
discover-topic-fig shows an example of a client looking for a topic
with a resource type (rt) of "temperature" using Discover.  The
client then receives the URI of the resource and its content-format.
A pubsub broker wishing to advertize topic discovery MUST use the
relation rt=core.ps.discover in the link.
This section defines the REST API exposed by a CoAP pubsub Broker to
pubsub Clients.  The examples throughout this section assume the use
of CoAP RFC7252.  A CoAP pubsub Broker implementing this
specification SHOULD support the DISCOVERY, CREATE, PUBLISH,
SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this
section.  Optimized implementations MAY support a subset of the
operations as required by particular constrained use cases.
CoAP pubsub Clients discover CoAP pubsub Brokers by using CoAP Simple
Discovery or through a Resource Directory (RD) I-D.ietf-core-
resource-directory.  A CoAP pubsub Broker SHOULD indicate its
presence and availability on a network by exposing a link to the
entry point of its pubsub API at its .well-known/core location
RFC6690.  A CoAP pubsub broker MAY register its pubsub REST API entry
point with a Resource Directory. discover-fig shows an example of a
client discovering a local pubsub API using CoAP Simple Discovery.  A
broker wishing to advertise the CoAP pubsub API for Simple Discovery
or through a Resource Directory MUST use the link relation
rt=core.ps.  A broker MAY advertise its supported content formats and
other attributes in the link to its pubsub API.
A CoAP pubsub Broker MAY offer a topic discovery entry point to
enable Clients to find topics of interest, either by topic name or by
link attributes which may be registered when the topic is created.
discover-topic-fig shows an example of a client looking for a topic
with a resource type (rt) of "temperature" using Discover.  The
client then receives the URI of the resource and its content-format.
A pubsub broker wishing to advertize topic discovery MUST use the
relation rt=core.ps.discover in the link.
pubsub API path (optional).  The base URI path of the pubsub
API, as obtained from discovery, used to discover topics.
The desired topic to return links for (optional).
Query Filter (optional).  MAY contain a query filter list as
per RFC6690 Section 4.1.
Clients create new topics on the broker using CREATE.  A client
wishing to create a topic MUST use CoAP POST to the pubsub API with a
payload indicating the desired topic.  The topic specification sent
in the payload MUST use a supported serialization of the CoRE link
format RFC6690.  The target of the link MUST be a URI formatted
string.  The client MUST indicate the desired content format for
publishes to the topic by using the ct (Content Format) link
attribute in the link-format payload.  The client MAY indicate the
lifetime of the topic by including the Max-Age option in the CREATE
request.
A CoAP pubsub broker MAY allow Clients to create new topics on the
broker using CREATE.  A client wishing to create a topic MUST use
CoAP POST to the pubsub API with a payload indicating the desired
topic.  The topic specification sent in the payload MUST use a
supported serialization of the CoRE link format RFC6690.  The target
of the link MUST be a URI formatted string.  The client MUST indicate
the desired content format for publishes to the topic by using the ct
(Content Format) link attribute in the link-format payload.  The
client MAY indicate the lifetime of the topic by including the Max-
Age option in the CREATE request.
pubsub API path (mandatory).  The path of the pubsub API, as
obtained from discovery.  A pubsub broker SHOULD use the value
"ps" for this variable whenever possible.
A CoAP pubsub Client uses the PUBLISH interface for updating topics
on the broker.  A client MAY use the PUT or the POST method to
publish state updates to the CoAP pubsub Broker.  A client MUST use
the content format specified upon creation of a given topic to
publish updates to that topic.  The broker MUST reject publish
operations which do not use the specified content format.  A CoAP
client publishing on a topic MAY indicate the maximum lifetime of the
value by including the Max-Age option in the publish request.  The
broker MUST return a response code of "2.04 Changed" if the publish
is accepted.  A Broker MAY return a "4.04 Not Found" if the topic
does not exist.  A broker MAY return "4.29 Too Many Requests" if
simple flow control as described in sec-flow-control is implemented.
A CoAP pubsub broker MAY allow clients to PUBLISH to topics on the
broker.  A client MAY use the PUT or the POST method to publish state
updates to the CoAP pubsub Broker.  A client MUST use the content
format specified upon creation of a given topic to publish updates to
that topic.  The broker MUST reject publish operations which do not
use the specified content format.  A CoAP client publishing on a
topic MAY indicate the maximum lifetime of the value by including the
Max-Age option in the publish request.  The broker MUST return a
response code of "2.04 Changed" if the publish is accepted.  A Broker
MAY return a "4.04 Not Found" if the topic does not exist.  A broker
MAY return "4.29 Too Many Requests" if simple flow control as
described in sec-flow-control is implemented.
A Broker MAY accept PUBLISH operations using the POST method.  If a
broker accepts PUBLISH using POST it MAY store an ordered list of
published representations, with an element of the list for each
published representation.  A Broker MAY reject, or delay responses
to, POST requests if the internal capacity to store representations
is exceeded.
A Broker MAY accept PUBLISH operations using the POST method.  If a
broker accepts PUBLISH using POST it shall respond with the 2.04
Changed status code.
The desired topic to publish on.
CoAP pubsub Clients subscribe to topics on the Broker using CoAP
Observe as described in RFC7641.  A CoAP pubsub Client wishing to
Subscribe to a topic on a broker MUST use a CoAP GET with Observe
registration.  The Broker MAY add the client to a list of observers.
The Broker MUST return a response code of "2.05 Content" along with
the most recently published value if the topic contains a valid value
and the broker can supply the requested content format.  The broker
MUST reject Subscribe requests on a topic if the content format of
the request is not supported by the content format the topic was
created with.  The broker MAY accept Subscribe requests which specify
content formats that the broker can supply as alternate content
formats to the content format the topic was registered with.  If the
topic was published with the Max-Age option, the broker MUST set the
Max-Age option in the valid response to the amount of time remaining
for the value to be valid since the last publish operation on that
topic.  The Broker MUST return a response code of "2.04 No Content"
if the Max-Age of the previously stored value has expired.  The
Broker MUST return a response code "4.04 Not Found" if the topic does
not exist or has been removed.  The Broker MUST return a response
code "4.15 Unsupported Content Format" if it can not return the
requested content format.  If a Broker is unable to accept a new
Subscription on a topic, it SHOULD return the appropriate response
code without the Observe option as per as per RFC7641 Section 4.1.
There is no explicit maximum lifetime of a Subscription, thus a
Broker may remove subscribers at any time.  The Broker, upon removing
a Subscriber, will transmit the appropriate response code without the
Observe option, as per RFC7641 Section 4.2, to the removed
Subscriber.
A CoAP pubsub broker MAY allow Clients to subscribe to topics on the
Broker using CoAP Observe as described in RFC7641.  A CoAP pubsub
Client wishing to Subscribe to a topic on a broker MUST use a CoAP
GET with the Observe option set to 0 (zero).  The Broker MAY add the
client to a list of observers.  The Broker MUST return a response
code of "2.05 Content" along with the most recently published value
if the topic contains a valid value and the broker can supply the
requested content format.  The broker MUST reject Subscribe requests
on a topic if the content format of the request is not supported by
the content format the topic was created with.  The broker MAY accept
Subscribe requests which specify content formats that the broker can
supply as alternate content formats to the content format the topic
was registered with.  If the topic was published with the Max-Age
option, the broker MUST set the Max-Age option in the valid response
to the amount of time remaining for the value to be valid since the
last publish operation on that topic.  The Broker MUST return a
response code of "2.07 No Content" if the Max-Age of the previously
stored value has expired.  The Broker MUST return a response code
"4.04 Not Found" if the topic does not exist or has been removed.
The Broker MUST return a response code "4.15 Unsupported Content
Format" if it can not return the requested content format.  If a
Broker is unable to accept a new Subscription on a topic, it SHOULD
return the appropriate response code without the Observe option as
per as per RFC7641 Section 4.1.  There is no explicit maximum
lifetime of a Subscription, thus a Broker may remove subscribers at
any time.  The Broker, upon removing a Subscriber, will transmit the
appropriate response code without the Observe option, as per RFC7641
Section 4.2, to the removed Subscriber.
The desired topic to subscribe to.
CoAP pubsub Clients unsubscribe from topics on the Broker using the
CoAP Cancel Observation operation.  A CoAP pubsub Client wishing to
unsubscribe to a topic on a Broker MUST either use CoAP GET with
Observe using an Observe parameter of 1 or send a CoAP Reset message
in response to a publish, as per RFC7641.
If a CoAP pubsub broker allows clients to SUBSCRIBE to topics on the
broker, it MUST allow Clients to unsubscribe from topics on the
Broker using the CoAP Cancel Observation operation.  A CoAP pubsub
Client wishing to unsubscribe to a topic on a Broker MUST either use
CoAP GET with Observe using an Observe parameter of 1 or send a CoAP
Reset message in response to a publish, as per RFC7641.
The desired topic to unsubscribe from.
A CoAP pubsub client wishing to obtain only the most recent published
value on a topic MAY use the READ interface.  For reading, the client
uses the CoAP GET method.  The broker MUST accept Read requests on a
topic if the content format of the request matches the content format
the topic was created with.  The broker MAY accept Read requests
which specify content formats that the broker can supply as alternate
content formats to the content format the topic was registered with.
The Broker MUST return a response code of "2.05 Content" along with
the most recently published value if the topic contains a valid value
and the broker can supply the requested content format.  If the topic
was published with the Max-Age option, the broker MUST set the Max-
Age option in the valid response to the amount of time remaining for
the topic to be valid since the last publish.  The Broker MUST return
a response code of "2.04 No Content" if the Max-Age of the previously
stored value has expired.  The Broker MUST return a response code
"4.04 Not Found" if the topic does not exist or has been removed.
The Broker MUST return a response code "4.15 Unsupported Content
Format" if the broker can not return the requested content format.
A CoAP pubsub broker MAY accept Read requests on a topic using the
the CoAP GET method if the content format of the request matches the
content format the topic was created with.  The broker MAY accept
Read requests which specify content formats that the broker can
supply as alternate content formats to the content format the topic
was registered with.  The Broker MUST return a response code of "2.05
Content" along with the most recently published value if the topic
contains a valid value and the broker can supply the requested
content format.  If the topic was published with the Max-Age option,
the broker MUST set the Max-Age option in the valid response to the
amount of time remaining for the topic to be valid since the last
publish.  The Broker MUST return a response code of "2.07 No Content"
if the Max-Age of the previously stored value has expired.  The
Broker MUST return a response code "4.04 Not Found" if the topic does
not exist or has been removed.  The Broker MUST return a response
code "4.15 Unsupported Content Format" if the broker can not return
the requested content format.
The desired topic to READ.
A CoAP pubsub Client wishing to remove a topic MAY use the CoAP
Delete operation on the URI of the topic.  The CoAP pubsub Broker
MUST return "2.02 Deleted" if the remove operation is successful.
The broker MUST return the appropriate 4.xx response code indicating
the reason for failure if the topic can not be removed.  When a topic
is removed for any reason, the Broker SHOULD return the response code
observers as per as per RFC7641 Section 3.2.  If a topic which has
sub-topics is removed, then all of its sub-topics MUST be recursively
removed.
A CoAP pubsub broker MAY allow clientsremove a topics from the broker
using the CoAP Delete method on the URI of the topic.  The CoAP
pubsub Broker MUST return "2.02 Deleted" if the removal is
successful.  The broker MUST return the appropriate 4.xx response
code indicating the reason for failure if the topic can not be
removed.  When a topic is removed for any reason, the Broker SHOULD
return the response code 4.04 Not Found and remove all of the
observers from the list of observers as per as per RFC7641
Section 3.2.  If a topic which has sub-topics is removed, then all of
its sub-topics MUST be recursively removed.
The desired topic to REMOVE.
A CoAP pubsub Broker may register the base URI of a pubsub API with a
Resource Directory.  A pubsub Client may use an RD to discover a
pubsub Broker.
A CoAP pubsub Broker may register the base URI, which is the REST API
entry point for a pubsub service, with a Resource Directory.  A
pubsub Client may use an RD to discover a pubsub Broker.
Depending on the level of trust users and system designers place in
the CoAP pubsub broker, the use of end-to-end object security is
RECOMMENDED I-D.ietf-core-object-security.
When only end-to-end encryption is necessary and the CoAP Broker is
trusted, Payload Only Protection (Mode:PAYL) could be used.  The
Publisher would wrap only the payload before sending it to the broker
and set the option Content-Format to application/smpayl.  Upon
receival, the Broker can read the unencrypted CoAP header to forward
it to the subscribers.
Depending on the level of trust users and system designers place in
the CoAP pubsub broker, the use of end-to-end object security is
RECOMMENDED as described in I-D.palombini-ace-coap-pubsub-profile.
When only end-to-end encryption is necessary and the CoAP Broker is
trusted, Payload Only Protection (Mode:PAYL) could be used.  The
Publisher would wrap only the payload before sending it to the broker
and set the option Content-Format to application/smpayl.  Upon
receival, the Broker can read the unencrypted CoAP header to forward
it to the subscribers.
Description: Add No Content response to GET to the existing
definition of the 2.04 response code.
Description: Add No Content response to GET to the existing
definition of the 2.07 response code.
Notes: The server sends this code to the client to indicate that
the request was valid and accepted, but the responce may contain
an empty payload.  It is comparable to and may be proxied with the
http 204 No Content status code.