Skip to content
Permalink
master
Switch branches/tags

coap-pubsub/proposal.txt

Go to file
 
 
Cannot retrieve contributors at this time
319 lines (198 sloc) 8.26 KB
Raw Blame
M. Koster
A. Keränen
K. Hartke
August 1, 2019
Proposal for PubSub Broker Improvements
1. Overview
This document provides a rough sketch for improving the PubSub Broker by
splitting topics into a "configuration resource" and a "data resource".
___ Topic Collection Resources
/ \ * get list of topics
\___/ * create a new topic by submitting
\ an initial topic configuration
\_______________________
\___ \___ \___ Topic Configuration Resources
/ \ / \ / \ * get current topic configuration
\___/ \___/ \___/ * update topic configuration
| | | * get topic metadata (see below)
| | ... | * delete topic
_|_ _|_ _|_
/ \ / \ / \ Topic Data Resources
\___/ \___/ \___/ * publish an item
* observe latest published item
The topic data resource does not exist until the first item has been
published. Before the first item has been published, the topic data resource
yields a 4.04 (Not Found) response. The creator of the topic could publish a
placeholder to create the data resource or simply not give the URI of the
data resource to a subscriber until a publisher has published something.
All topic URIs should be broker-generated. There does not need to be any URI
pattern dependence between the URI where the data exists and the URI of the
topic configuration. Configuration and data resources might even be hosted
on different servers.
2. Topic Configuration
Topic configurations and topic configuration updates are represented by
CoRAL documents.
When retrieving the representation of a topic configuration resource, the
CoRAL document includes both topic metadata and topic configuration data.
When updating a topic configuration resource, the CoRAL document includes
only the topic configuration data.
2.1 Topic Metadata (read-only)
Examples:
* Location of the topic data resource (URI)
* Has any published item (boolean)
* Created timestamp (date/time)
* Last modified timestamp (date/time)
* ...
2.2 Topic Configuration Data (read/write)
Examples:
* User-friendly topic description
* Allowed content format
* Location of the authorization server
* Rate limits
* Topic lifetime
* Tombstone representation
* ...
2.3 Data Resource Attributes (read/write)
Examples:
* Resource type
* Interface type
* Physical sensor location
* Unit of sensor value
* ...
3. Operations
3.1 Get List of Topics
Request:
GET </ps/topics>
Response:
2.05 Content
Content-Format: CoRAL
rdf:type <http://example.org/pubsub/topic-list>
topic </ps/topics/1234>
topic </ps/topics/1235>
topic </ps/topics/1236>
topic </ps/topics/1237>
The list of topics is a standard collection resource. The representation
consists of a list of links to the topic configuration resources. The
resource supports the typical create/read/update/delete operations.
(The example is missing the #using's...)
3.2 Filter List of Topics
Request:
GET </ps/topics?rt=oic.r.temperature>
Accept: CoRAL
Response:
2.05 Content
Content-Format: CoRAL
rdf:type <http://example.org/pubsub/topic-list>
topic </ps/topics/1234>
topic </ps/topics/1237>
It might be useful to use the same API as CoRAL Reef. Query parameters are
limited to a fixed, well-known set of attributes.
The Accept option could be used to express a preference between CoRAL and
(for legacy clients) CoRE Link Format in the response.
3.3 Filter List of Topics by Custom Attributes
Request:
FETCH </ps/topics>
Content-Format: CoRAL
topic _ {
topic-data _ {
<http://example.org/vocab/building> 18
<http://example.org/vocab/floor> 1
<http://example.org/vocab/unit> "Cel"
}
}
Response:
2.05 Content
Content-Format: CoRAL
rdf:type <http://example.org/pubsub/topic-list>
topic </ps/topics/1234>
(CoRAL FETCH is currently not yet defined but would probably work very
similarly to SenML FETCH.)
3.4 Create a New Topic by Submitting an Initial Topic Configuration
Request:
POST </ps/topics>
Content-Format: CoRAL
rdf:type <http://example.org/pubsub/topic>
topic-title "My Office Room Temperature"
Response:
2.01 Created
Content-Format: CoRAL
Location: </ps/topics/1234>
topic </ps/topics/1234>
topic-data </ps/data/1234>
If the creator of a topic just wants all the defaults, they can just submit
an empty CoRAL document.
The Accept option could be used to express a preference between CoRAL and
(for legacy clients) CoRE Link Format in the response.
3.5 Get Current Topic Configuration
Request:
GET </ps/topics/1234>
Response:
2.05 Content
Content-Format: CoRAL
rdf:type <http://example.org/pubsub/topic>
has-published-item true
created dt'2019-07-08T15:35:00+0200'
last-modified dt'2019-07-08T15:35:00+0200'
authorization-server <coaps://my-authorization-server.example/>
max-rate 50
expires dt'2019-07-15T15:35:00+0200'
publish -> </ps/data/1234> [ method 3 ]
topic-data </ps/data/1234> {
title "My Office Room Temperature"
rt "oic.r.temperature"
building 18
floor 1
unit "Cel"
}
Publishers should be given the form with the 'publish' operation type.
Subscribers should be given the link with the 'topic-data' relation type.
3.6 Update the Topic Configuration
Request:
PATCH </ps/topics/1234>
Content-Format: CoRAL
max-rate 60
Response:
2.04 Changed
(CoRAL PATCH is currently not yet defined but would probably work very
similarly to SenML PATCH.)
3.7 Delete the Topic
Request:
DELETE </ps/topics/1234>
Response:
2.02 Deleted
3.8 Publish an Item
A publisher can publish an item by submitting a form with the 'publish'
operation type.
Request:
PUT </ps/data/1234>
Content-Format: SenML
[...SenML data here...]
Response:
2.04 Changed
3.9 Get the Latest Published Item
Request:
GET </ps/data/1234>
Response:
2.05 Content
Content-Format: SenML
[...SenML data here...]
3.10 Observe the Latest Published Item
Request:
GET </ps/data/1234>
Observe: 0
Response:
2.05 Content
Content-Format: SenML
Observe: 9876
[...SenML data here...]
If the 2.05 (Content) response does not include an Observe option, the
subscriber can poll the resource.
4. References
Koster, M., Keränen, A., and J. Jiménez, "Publish-Subscribe Broker for the
Constrained Application Protocol (CoAP)", draft-ietf-core-coap-pubsub-08
(work in progress), March 2019.
Hartke, K., "The Constrained RESTful Application Language (CoRAL)",
draft-hartke-t2trg-coral-09 (work in progress), July 2019.
Acknowledgements
Thanks to Christian Amsüss, Carsten Bormann, and Jim Schaad for helpful
comments and discussions that have shaped the document.