idnits 2.17.1 draft-hartke-t2trg-data-hub-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 22, 2018) is 2013 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-hartke-t2trg-coral-06 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-05 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-15 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Experimental October 22, 2018 5 Expires: April 25, 2019 7 Thing-to-Thing Data Hub 8 draft-hartke-t2trg-data-hub-02 10 Abstract 12 The Thing-to-Thing Data Hub is a RESTful, hypermedia-driven Web 13 application that can be used in Thing-to-Thing communications to 14 share data items such as thing descriptions, configurations, resource 15 descriptions, or firmware updates at a central location. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 25, 2019. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 53 2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Interaction Model . . . . . . . . . . . . . . . . . . . . . . 5 55 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 57 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 59 6.2. Informative References . . . . . . . . . . . . . . . . . 8 60 Appendix A. Related Work . . . . . . . . . . . . . . . . . . . . 8 61 A.1. CoAP Publish-Subscribe . . . . . . . . . . . . . . . . . 8 62 A.2. CoRE Resource Directory . . . . . . . . . . . . . . . . . 9 63 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 66 1. Introduction 68 In Thing-to-Thing communication, there is often a need to share data 69 items of common interest at a central location. For example, the 70 CoRE Resource Directory [I-D.ietf-core-resource-directory] aggregates 71 descriptions of resources held on other servers, which enables Things 72 to easily discover these resources. Similarly, a W3C Web-of-Things 73 Thing Description Repository [WOT] stores semantic metadata of Things 74 as well as functional descriptions of their interfaces, making this 75 data available to Web dashboards, commissioning tools and other 76 things. 78 As more and more Thing-to-Thing applications are implemented, it 79 becomes increasingly important to be able to share not only resource 80 and Thing descriptions but also many other kinds of data, such as 81 default configurations for new devices, service locations, firmware 82 updates, or certificate revocation lists. The existing resource 83 directories and Thing description repositories are not a good fit for 84 these kinds of data, as they're specialized to their use cases and 85 don't accept any other kinds of data. Creating a new, specialized 86 application for each use case is not practical in the long term. 88 This document defines a simple "data hub" application, a RESTful Web 89 application with a hypermedia API that is suitable for constrained 90 environments and that generalizes the concept of a central repository 91 to sharing any kinds of data. A data hub enables clients to share 92 data items in any format and provides means for creating, reading, 93 observing, updating, deleting, and finding data items at a data hub 94 server. 96 Data hubs are intended to be used primarily with CoAP [RFC7252]. 98 Features: 100 o General 102 The data hub generalizes the concept of a directory or repository 103 to data items of any Internet media type. This means applications 104 using the data hub aren't stuck forever with the same media types 105 or limited to resource descriptions and Thing descriptions. 107 o Searchable 109 Clients can retrieve a subset of data items from a data hub based 110 on item metadata. 112 o Observable 114 Data items published to a data hub are exposed as resources. As 115 such, they can be observed for changes [RFC7641]. This allows 116 clients to stay informed of information that other clients update 117 over time. As a result, the data hub functions similar to a CoAP 118 Publish-Subscribe Broker [I-D.ietf-core-coap-pubsub], although 119 this isn't its primary use case. 121 o Evolvable 123 The key differentiator of the data hub compared to CoRE Resource 124 Directory and CoAP Publish-Subscribe Broker is the evolvability -- 125 the ability to respond effectively to the need for changes without 126 negatively impacting existing and new clients. Data hubs enable 127 fine-grained evolvability by driving all interactions by machine- 128 readable hypermedia elements. Features can be added, changed or 129 removed in a safe, backwards-compatible way simply by updating the 130 data hub representation to expose appropriate links and forms. 132 1.1. Requirements Notation 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 136 "OPTIONAL" in this document are to be interpreted as described in 137 [RFC2119]. 139 2. Data Model 141 The data model consists of three elements: the _data hub_, a 142 _data collection_, and a number of shared _data items_ (Figure 1). 144 Data Hub 145 +-----------------------------------------------+ 146 | ___ | 147 | Data / \ | 148 | Collection \___/ | 149 | | ___ | 150 | |________/ \ Data Item | 151 | | \___/ | 152 | | ___ | 153 | |________/ \ Data Item | 154 | | \___/ | 155 | | . | 156 | | . | 157 | | . | 158 | | ___ | 159 | |________/ \ Data Item | 160 | \___/ | 161 | | 162 +-----------------------------------------------+ 164 Figure 1: A Data Collection with a Number of Shared Data Items Hosted 165 at a Data Hub 167 Data Hub 169 A data hub is a Web application running at a Web server. It hosts 170 the data collection and the data items. 172 Data Collection 174 A data collection is a collection resource that contains the data 175 items. 177 Representations of data collections MUST have the "application/ 178 coral+cbor" or "text/coral" media type [I-D.hartke-t2trg-coral]. 179 They primarily consist of links to the data items using the "item" 180 link relation type [RFC6573]. To reduce the number of round- 181 trips, they MAY also embed (complete or partial) representations 182 of the data items. Forms contained in the representation enable 183 interactions with the collection and the data items, as described 184 in the following section. The representations MAY additionally 185 contain other links and forms that are not described in this 186 document, such as a link with the "alternate" link relation type 187 that references an alternate representation of the data collection 188 resource. 190 For a start, a data hub is defined to have a depth of only one 191 level; i.e., all data item resources are organized directly under 192 the top-level data collection resource. This could be extended to 193 multiple levels in a future revision of this document. 195 Data Item 197 A data item is a resource that is a member of the data collection 198 resource. 200 Data item representations MAY have any media type. However, a 201 data collection MAY restrict the media types it accepts for 202 publication. In this case, the form in the data collection 203 representation for creating data items MUST list the acceptable 204 media types using form fields with name . 206 The representations of the data items MAY link back to the data 207 collection resource using the "collection" link relation type 208 [RFC6573]. 210 3. Interaction Model 212 The interaction model consists of eight possible interactions with a 213 data collection: discovering and reading the data collection, and 214 creating, reading, observing, updating, deleting, and finding shared 215 data items in the data collection. 217 Discovering a Data Hub 219 For a start, this revision of the document assumes that clients 220 are pre-configured with a link to a data collection at some data 221 hub. 223 Reading a Collection 225 A client can retrieve a representation of a data collection by 226 following the pre-configured link. The representation of the data 227 collection includes links to (and, optionally, representations of) 228 the data items in the data collection. The representation of the 229 data collection also includes forms for creating, updating, 230 deleting, and finding data items. 232 Creating an Item 233 The representation of a data collection MAY contain a form with 234 the form relation type. Submitting this form 235 with a representation in one of the acceptable media types creates 236 a new data item in the data collection. The acceptable media 237 types are indicated by form fields. 239 Data hubs implementing this specification MUST offer the POST 240 method [RFC7252] in this form. The location of the created data 241 item is conveyed in the 2.01 (Created) response by the Location- 242 Path and Location-Query options [RFC7252]. 244 Reading an Item 246 A client can retrieve a representation of a data item by following 247 a link with the 248 link relation type in the data collection representation. 250 Observing an Item 252 A client can observe a data item by following a link with the 253 link relation type 254 in the data collection representation and observing the target 255 resource as specified in RFC 7641 [RFC7641]. 257 Updating an Item 259 For each data item in a data collection, the representation of the 260 data collection MAY include a nested form with the 261 form relation type. Submitting this form updates 262 the data item to the submitted representation. 264 Data hubs implementing this specification MUST offer the PUT 265 method [RFC7252] in this form. 267 Deleting an Item 269 For each data item in a data collection, the representation of the 270 data collection MAY include a nested form with the 271 form relation type. Submitting this form deletes 272 the data item from the data collection. 274 Data hubs implementing this specification MUST offer the DELETE 275 method [RFC7252] in this form. 277 Searching for Items 279 The representation of a data collection MAY contain a form with 280 the form relation type. This form can be used to 281 find data items in the data collection. Submitting this form with 282 a search query returns the subset of data items that match the 283 query. 285 Data hubs implementing this specification MUST offer the FETCH 286 method [RFC8132] in this form. 288 4. Security Considerations 290 TODO. 292 5. IANA Considerations 294 This document has no IANA actions. 296 6. References 298 6.1. Normative References 300 [I-D.hartke-t2trg-coral] 301 Hartke, K., "The Constrained RESTful Application Language 302 (CoRAL)", draft-hartke-t2trg-coral-06 (work in progress), 303 October 2018. 305 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 306 Requirement Levels", BCP 14, RFC 2119, 307 DOI 10.17487/RFC2119, March 1997, 308 . 310 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 311 RFC 6573, DOI 10.17487/RFC6573, April 2012, 312 . 314 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 315 Application Protocol (CoAP)", RFC 7252, 316 DOI 10.17487/RFC7252, June 2014, 317 . 319 [RFC7641] Hartke, K., "Observing Resources in the Constrained 320 Application Protocol (CoAP)", RFC 7641, 321 DOI 10.17487/RFC7641, September 2015, 322 . 324 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 325 FETCH Methods for the Constrained Application Protocol 326 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 327 . 329 6.2. Informative References 331 [I-D.ietf-core-coap-pubsub] 332 Koster, M., Keranen, A., and J. Jimenez, "Publish- 333 Subscribe Broker for the Constrained Application Protocol 334 (CoAP)", draft-ietf-core-coap-pubsub-05 (work in 335 progress), July 2018. 337 [I-D.ietf-core-resource-directory] 338 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 339 Amsuess, "CoRE Resource Directory", draft-ietf-core- 340 resource-directory-15 (work in progress), October 2018. 342 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 343 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 344 . 346 [WOT] Kovatsch, M., Ed. and D. Peintner, Ed., "WoT Current 347 Practices", February 2018, . 350 Appendix A. Related Work 352 The data hub is an instance of the well-known collection pattern. As 353 such, it might be used in places where a more specialized instance of 354 the collection pattern is currently used, such as the CoAP Publish- 355 Subscribe Broker [I-D.ietf-core-coap-pubsub] or the CoRE Resource 356 Directory [I-D.ietf-core-resource-directory]. This section shows how 357 these two applications might be implemented with a data hub (without 358 trying to replicate all of their features in detail). 360 A.1. CoAP Publish-Subscribe 362 CoAP Publish-Subscribe [I-D.ietf-core-coap-pubsub] provides means for 363 resource-constrained sensor and actuator nodes to publish and receive 364 data without having to be available at the same time. The basic 365 operation involves clients called "publishers" updating "topic" 366 resources at a server called the "broker" and clients called 367 "subscribers" observing these resources (Figure 2). 369 ____________ ____________ ____________ 370 | |---------.| | | | 371 | Publisher |<--------'| Broker | | Subscriber | 372 | (Client) | | (Server) |.---------| (Client) | 373 |____________| |____________|'-------->|____________| 375 Figure 2: CoAP Publish-Subscribe 377 A broker might be implemented as a data hub by creating the topics as 378 resources on the data hub server and linking to these from the data 379 collection resource (Figure 3). Hypermedia controls in the data 380 collection representation enable publishers to create, update, and 381 delete topics as well as subscribers to read or observe these topics. 383 Data Hub 384 +--------------------------------+ 385 | ___ | 386 | / \ Data Collection | 387 | \___/ | 388 | | ___ | 389 | |________/ \ Topic A | 390 | | \___/ | 391 | | ___ | 392 | |________/ \ Topic B | 393 | | \___/ | 394 | | ___ | 395 | |________/ \ Topic C | 396 | \___/ | 397 | | 398 +--------------------------------+ 400 Figure 3: A Data Hub Acting as a Publish-Subscribe Broker 402 +-------------+--------------------------+ 403 | Interaction | Mapped to | 404 +-------------+--------------------------+ 405 | DISCOVERY | Discovering a Data Hub / | 406 | | Reading a Collection / | 407 | | Searching for Items | 408 | CREATE | Creating an Item | 409 | PUBLISH | Updating an Item | 410 | SUBSCRIBE | Observing an Item | 411 | UNSUBSCRIBE | Observing an Item | 412 | READ | Reading an Item | 413 | REMOVE | Deleting an Item | 414 +-------------+--------------------------+ 416 Table 1: Mapping of Pub/Sub Interactions to Data Hub 418 A.2. CoRE Resource Directory 420 A CoRE Resource Directory [I-D.ietf-core-resource-directory] hosts 421 descriptions of resources held on other servers, allowing lookups to 422 be performed for those descriptions. The descriptions are encoded as 423 links in CoRE Link Format [RFC6690]. The links are annotated with a 424 variety of link attributes providing the type of and hints about the 425 linked resources. 427 Data Hub 428 +-------------------------------------+ 429 | ___ | 430 | / \ Data Collection | 431 | \___/ | 432 | | ___ | 433 | |________/ \ Data Item in | +----------------------+ 434 | | \___/ Link Format | | ___ | 435 | | |___________________|____|____/ \ Resource | 436 | | | | | \___/ | 437 | | | | | ___ | 438 | | |___________________|____|____/ \ Resource | 439 | | | | \___/ | 440 | | | | | 441 | | ___ | +----------------------+ 442 | |________/ \ Data Item in | +----------------------+ 443 | \___/ Link Format | | ___ | 444 | |___________________|____|____/ \ Resource | 445 | | | \___/ | 446 | | | | 447 +-------------------------------------+ +----------------------+ 449 Figure 4: A Data Hub Storing Link Format Items 451 A data hub might be used to store these resource descriptions. Each 452 resource description becomes a data item in a data collection 453 (Figure 4). A specialized interface for querying the cumulative set 454 of stored links might be provided separately. 456 +-----------------------+------------------------+ 457 | Interaction | Mapped to | 458 +-----------------------+------------------------+ 459 | Discovery | Discovering a Data Hub | 460 | Registration | Creating an Item | 461 | Registration Update | - | 462 | Registration Removal | Deleting an Item | 463 | Read Endpoint Links | Reading an Item | 464 | Update Endpoint Links | Updating an Item | 465 +-----------------------+------------------------+ 467 Table 2: Mapping of Resource Directory Interactions to Data Hub 469 Acknowledgements 471 Thanks to Christian Amsuess and Jaime Jimenez for helpful comments 472 and discussions that have shaped the document. 474 Author's Address 476 Klaus Hartke 477 Ericsson 478 Torshamnsgatan 23 479 Stockholm SE-16483 480 Sweden 482 Email: klaus.hartke@ericsson.com