proposal.txt

                                                                       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.