idnits 2.17.1 draft-hartke-t2trg-bulletin-board-01.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 30, 2016) is 2697 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-08) exists of draft-hartke-core-apps-05 == Outdated reference: A later version (-09) exists of draft-hartke-t2trg-coral-01 == Outdated reference: A later version (-13) exists of draft-ietf-core-coap-pubsub-00 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-08 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). 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 Universitaet Bremen TZI 4 Intended status: Experimental October 30, 2016 5 Expires: May 3, 2017 7 Thing-to-Thing Bulletin Board 8 draft-hartke-t2trg-bulletin-board-01 10 Abstract 12 A Thing-to-Thing Bulletin Board is a RESTful, hypermedia-driven Web 13 application that can be used in Thing-to-Thing communication to 14 publish information such as thing descriptions, configurations, 15 resource descriptions or sleep schedules 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 http://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 May 3, 2017. 34 Copyright Notice 36 Copyright (c) 2016 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 (http://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. Related Work . . . . . . . . . . . . . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Bulletin Boards . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Data Model . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.2. Interaction Model . . . . . . . . . . . . . . . . . . . . 5 57 2.3. Application Description . . . . . . . . . . . . . . . . . 6 58 3. Interoperability Considerations . . . . . . . . . . . . . . . 7 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 61 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 63 6.2. Informative References . . . . . . . . . . . . . . . . . 8 64 Appendix A. Proof-of-Concept . . . . . . . . . . . . . . . . . . 8 65 A.1. CoRE Lighting . . . . . . . . . . . . . . . . . . . . . . 8 66 A.2. CoAP Publish-Subscribe . . . . . . . . . . . . . . . . . 10 67 A.3. CoRE Resource Directory . . . . . . . . . . . . . . . . . 11 68 A.4. CoRE Mirror Server . . . . . . . . . . . . . . . . . . . 12 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 71 1. Introduction 73 CoRE Lighting [I-D.hartke-core-lighting] defines a "bulletin board" 74 application that can be used to share the thing descriptions of 75 sensor and actuator nodes. This document generalizes the bulletin 76 board concept to support representations in any media type and 77 defines means for creating, reading, observing, updating, deleting 78 and finding items in a bulletin board. 80 The generalization to any media type provides two advantages. The 81 first is media type agility: applications won't be stuck forever with 82 the media types of CoRE Lighting. The second is that it may be 83 useful to share also other information than thing descriptions, such 84 as default configurations for new devices, service locations or sleep 85 schedules. 87 Finding items by submitting a search query allows clients to retrieve 88 a subset of items from a bulletin board. In CoRE Lighting, a client 89 has to download the whole set of thing descriptions, filter the set 90 and configure compatible devices. It may be more efficient to filter 91 the set at the bulletin board server. To make this work with any 92 media type, a search request needs to specify both the media type of 93 the desired items and a media type-specific search query. 95 The generalized bulletin board is presented as a CoRE Application 96 Description [I-D.hartke-core-apps]. That is, the focus of the 97 application interface is on the media types used in the bulletin 98 board application and interactions are driven by links and forms. 100 1.1. Related Work 102 The bulletin board is an instance of the well-known REST collection 103 pattern. As such, it might be used in places where a more specific 104 instance of the collection pattern is currently used, such as the 105 Publish-Subscribe Broker [I-D.ietf-core-coap-pubsub] or the CoRE 106 Resource Directory [I-D.ietf-core-resource-directory]. Appendix A 107 explores this direction and provides a proof-of-concept mapping from 108 publish-subscribe broker and resource directory to bulletin boards. 110 The key differentiator of the bulletin board compared to publish- 111 subscribe broker and resource directory lies in the evolvability, the 112 ability to respond effectively to change (such as the introduction of 113 new features) without negatively impacting existing and new clients. 114 The definition of interfaces purely in terms of standardized URI 115 templates makes it very difficult to gradually evolve them; there are 116 no versioning or capability negotiation mechanisms. The bulletin 117 board facilitates fine-grained evolvability by driving all 118 interactions through machine-understandable hypertext. Features can 119 be added, changed or removed in a backwards-compatible way simply by 120 updating the bulletin board to expose corresponding links and forms. 122 1.2. Terminology 124 Readers are expected to be familiar with the terms and concepts 125 described in [RFC5988], [RFC6573], and [I-D.hartke-core-apps]. 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in 130 [RFC2119]. 132 2. Bulletin Boards 134 This section defines the data model and the interaction model of 135 bulletin boards. 137 2.1. Data Model 139 The data model consists of two elements: the bulletin board and a 140 number of published items (Figure 1). 142 ___ 143 Bulletin / \ 144 Board \___/ ___ 145 |__________/ \ Item 1 146 | item \___/ 147 | ___ 148 |__________/ \ Item 2 149 | item \___/ 150 | . 151 | . 152 | . 153 | ___ 154 |__________/ \ Item N 155 item \___/ 157 Figure 1: A Bulletin Board with a Number of Published Items 159 Bulletin Board 161 A bulletin board is a Web application intended for the posting of 162 public messages, for example, to share thing descriptions, 163 announce services or provide information. Sensor and actuator 164 nodes can leave and erase messages for other nodes to read and 165 see. 167 A bulletin board resource is a collection of published items. Its 168 representation consists primarily of links to the item resources 169 using the "item" link relation type [RFC6573]. To reduce the 170 number of round-trips, it can also embed (complete or partial) 171 representations of those item resources. Forms contained in the 172 representation enable interactions with the bulletin board. 174 For a start, a bulletin board has only a depth of one level; i.e., 175 all published items are organized directly under the bulletin 176 board resource. This could be extended to multiple levels in a 177 future revision of this draft. 179 Bulletin board representations are formatted in the "application/ 180 coral" media type [I-D.hartke-t2trg-coral]. 182 Item 184 A bulletin board item is a member of the collection. 186 Item representations can in principle be formatted in any media 187 type; a bulletin board deployment MAY restrict the media types it 188 accepts for publication, though. 190 The representations of items MAY link back to a bulletin board 191 resource using the "collection" link relation type [RFC6573]. 193 2.2. Interaction Model 195 The interaction model consists of eight possible interactions with a 196 bulletin board: discovering and reading the bulletin board, and 197 creating, reading, observing, updating, deleting and finding 198 published items in the bulletin board. 200 Discovery 202 For a start, nodes are assumed to be pre-configured out-of-band 203 with a link to a bulletin board. 205 Read Bulletin Board 207 A node can retrieve a representation of the bulletin board by 208 following the discovered link. The representation of the bulletin 209 board includes links to and/or literals with representations of 210 the items in the bulletin board. The representation MAY also 211 include forms for creating, updating, deleting and finding items. 213 Create Item 215 The representation of a bulletin board MAY contain a form with the 216 "create-item" form relation type. Submitting this form with a 217 representation in one of the accepted content formats creates a 218 new item in the bulletin board. 220 Read Item 222 A node can retrieve a representation of an item by following one 223 of the links with the "item" link relation type in the 224 representation of the bulletin board. 226 Observe Item 228 A node can observe an item by following one of the links with the 229 "item" link relation type in the representation of the bulletin 230 board and observing the resource as specified in [RFC7641]. 232 Update Item 234 For each item in a bulletin board, the representation of the 235 bulletin board MAY indicate that the item is updatable. If an 236 item is updatable, the link to the item includes the CoRAL 237 Updatable Option, which defines a form with the "update" form 238 relation type. Submitting this form updates the item in the 239 bulletin board to the submitted representation. 241 Delete Item 243 For each item in a bulletin board, the representation of the 244 bulletin board MAY indicate that the item is deletable. If an 245 item is deletable, the link to the item includes the CoRAL 246 Deletable Option, which defines a form with the "delete" form 247 relation type. Submitting this form deletes the item from the 248 bulletin board. 250 Find Items 252 A form with the "search" form relation type can be used to find 253 items. Submitting this form with a media type and a media type- 254 specific filter query returns a subset of the bulletin board that 255 matches the filter. (The details of this are TBD.) 257 2.3. Application Description 259 Application name: 260 Thing-to-Thing Bulletin Board 1.0 262 URI schemes: 263 coap [RFC7252] 265 Media types: 266 application/coral [I-D.hartke-t2trg-coral] 268 Link relation types: 269 collection [RFC6573] 270 item [RFC6573] 272 Form relation types: 273 create-item [I-D.hartke-core-apps] 274 update [I-D.hartke-core-apps] 275 delete [I-D.hartke-core-apps] 276 search [I-D.hartke-core-apps] 278 Form field names: 279 None. 281 Well-known locations: 282 None. 284 Interoperability considerations: 285 See Section 3. 287 Security considerations: 288 See Section 4. 290 Contact: 291 See "Author's Address" section. 293 Author/Change controller: 294 IESG 296 3. Interoperability Considerations 298 TODO. 300 4. Security Considerations 302 TODO. 304 5. IANA Considerations 306 This document includes no request to IANA. 308 6. References 310 6.1. Normative References 312 [I-D.hartke-core-apps] 313 Hartke, K., "CoRE Application Descriptions", draft-hartke- 314 core-apps-05 (work in progress), October 2016. 316 [I-D.hartke-t2trg-coral] 317 Hartke, K., "The Constrained RESTful Application Language 318 (CoRAL)", draft-hartke-t2trg-coral-01 (work in progress), 319 October 2016. 321 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 322 Requirement Levels", BCP 14, RFC 2119, 323 DOI 10.17487/RFC2119, March 1997, 324 . 326 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 327 RFC 6573, DOI 10.17487/RFC6573, April 2012, 328 . 330 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 331 Application Protocol (CoAP)", RFC 7252, 332 DOI 10.17487/RFC7252, June 2014, 333 . 335 [RFC7641] Hartke, K., "Observing Resources in the Constrained 336 Application Protocol (CoAP)", RFC 7641, 337 DOI 10.17487/RFC7641, September 2015, 338 . 340 6.2. Informative References 342 [I-D.hartke-core-lighting] 343 Hartke, K., "CoRE Lighting", draft-hartke-core-lighting-00 344 (work in progress), September 2015. 346 [I-D.ietf-core-coap-pubsub] 347 Koster, M., Keranen, A., and J. Jimenez, "Publish- 348 Subscribe Broker for the Constrained Application Protocol 349 (CoAP)", draft-ietf-core-coap-pubsub-00 (work in 350 progress), October 2016. 352 [I-D.ietf-core-resource-directory] 353 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 354 Resource Directory", draft-ietf-core-resource-directory-08 355 (work in progress), July 2016. 357 [I-D.vial-core-mirror-server] 358 Vial, M., "CoRE Mirror Server", draft-vial-core-mirror- 359 server-01 (work in progress), April 2013. 361 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 362 DOI 10.17487/RFC5988, October 2010, 363 . 365 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 366 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 367 . 369 Appendix A. Proof-of-Concept 371 There are a number of specifications (CoRE Lighting, CoAP Publish- 372 Subscribe Broker, CoRE Resource Directory and CoRE Mirror Server) 373 that implement variations of the collection pattern. This section 374 shows how they might be implemented using a bulletin board (without 375 trying to replicate them in full detail). 377 A.1. CoRE Lighting 379 CoRE Lighting [I-D.hartke-core-lighting] uses a JSON-based bulletin 380 board to discover "things" such as light bulbs and light switches. 381 Things are described by a thing description that contains both human- 382 readable information and machine-understandable hypermedia controls 383 which indicate the possible interactions with the thing. 385 +----------------------------------+ 386 | ___ | 387 | / \ Bulletin Board | 388 | \___/ ___ | 389 | |__________/ \ Thing | +------------------------+ 390 | | item \___/ Description | | ___ | 391 | | |________________|____|__/ \ Light Bulb | 392 | | config | | \___/ Configuration | 393 | | | | | 394 | | ___ | +------------------------+ 395 | |__________/ \ Thing | +------------------------+ 396 | item \___/ Description | | ___ | 397 | |________________|____|__/ \ Light Remote | 398 | about | | \___/ Control State | 399 | | | | 400 +----------------------------------+ +------------------------+ 402 Figure 2: A Bulletin Board Storing Thing Descriptions 404 Matching the example in Section 5.2.1 of [I-D.hartke-core-lighting], 405 Figure 2 shows a bulletin board with two thing descriptions. The 406 first thing description describes a light bulb and has a link with 407 the "config" link relation type pointing to the configuration of the 408 light bulb. The second thing description describes a light remote 409 control (LRC) and has a link with the "about" link relation type 410 pointing to the observable state of the LRC. 412 Thing descriptions are represented in the "application/thing- 413 description+json" media type (content format 65200 in the example). 414 A bulletin board representation thus could look as shown in Figure 3. 416 ______________________________ 417 | | 418 | Form | 419 | relation: 1 (create-item) | 420 | method: 2 (POST) | 421 | accept: 65200 | 422 |______________________________| 423 | | 424 | Literal | 425 | relation: 33 (item) | 426 | format: 65200 | 427 | ________________________ | 428 | | | | 429 | | Thing Description 1 | | 430 | |________________________| | 431 |______________________________| 432 | | 433 | Literal | 434 | relation: 33 (item) | 435 | format: 65200 | 436 | ________________________ | 437 | | | | 438 | | Thing Description 2 | | 439 | |________________________| | 440 |______________________________| 442 Figure 3: A Bulletin Board Representation With Two Thing Descriptions 444 A.2. CoAP Publish-Subscribe 446 CoAP Publish-Subscribe [I-D.ietf-core-coap-pubsub] provides means for 447 sensor and actuator nodes with limited reachability to publish and 448 receive data without having to be reachable at the same time. The 449 basic operation involves clients called "publishers" updating "topic" 450 resources at a server called the "broker", and clients called 451 "subscribers" observing these resources (Figure 4). 453 ____________ ____________ ____________ 454 | |--------->| | | | 455 | Publisher |<---------| Broker | | Subscriber | 456 | (Client) | | (Server) |<---------| (Client) | 457 |____________| |____________|--------->|____________| 459 Figure 4: CoAP Publish-Subscribe 461 A broker might be implemented as a bulletin board by creating the 462 topics as resources on the bulletin board server and linking to these 463 from the bulletin board resource with the "item" link relation type 464 (Figure 5). Hypermedia controls in the bulletin board representation 465 enable publishers to create, update and delete topics, and 466 subscribers to read/observe these topics. 468 +------------------------------+ 469 | ___ | 470 | / \ Bulletin Board | 471 | \___/ ___ | 472 | |__________/ \ Topic A | 473 | | item \___/ | 474 | | ___ | 475 | |__________/ \ Topic B | 476 | | item \___/ | 477 | | ___ | 478 | |__________/ \ Topic C | 479 | item \___/ | 480 | | 481 +------------------------------+ 483 Figure 5: A Bulletin Board Acting as a Publish-Subscribe Broker 485 +-------------+------------------------+ 486 | Interaction | Mapped to | 487 +-------------+------------------------+ 488 | DISCOVER | Discovery / | 489 | | Read Bulletin Board / | 490 | | Find Items | 491 | CREATE | Create Item | 492 | PUBLISH | Update Item | 493 | SUBSCRIBE | Observe Item | 494 | UNSUBSCRIBE | Observe Item | 495 | READ | Read Item | 496 | REMOVE | Delete Item | 497 +-------------+------------------------+ 499 Table 1: Mapping of Pub/Sub Interactions to Bulletin Board 501 A.3. CoRE Resource Directory 503 A CoRE Resource Directory [I-D.ietf-core-resource-directory] hosts 504 descriptions of resources held on other servers, allowing lookups to 505 be performed for those resources. The descriptions are encoded as 506 links in CoRE Link Format [RFC6690] that are annotated with a variety 507 of link attributes providing the type of and hints about the linked 508 resources. 510 +----------------------------------+ 511 | ___ | 512 | / \ Bulletin Board | 513 | \___/ ___ | 514 | |__________/ \ Link Format | +------------------------+ 515 | | item \___/ Resource | | ___ | 516 | | |________________|____|__/ \ Resource A | 517 | | hosts | | \___/ | 518 | | | | | 519 | | ___ | +------------------------+ 520 | |__________/ \ Link Format | +------------------------+ 521 | item \___/ Resource | | ___ | 522 | |________________|____|__/ \ Resource B | 523 | hosts | | \___/ | 524 | | | | 525 +----------------------------------+ +------------------------+ 527 Figure 6: A Bulletin Board Storing Links 529 A bulletin board might store these resource descriptions such that 530 each resource description becomes one item in the bulletin board and 531 each item links to the respective resource (Figure 6). 533 +-----------------------+-------------+ 534 | Interaction | Mapped to | 535 +-----------------------+-------------+ 536 | Discovery | Discovery | 537 | Registration | Create Item | 538 | Update | Update Item | 539 | Removal | Delete Item | 540 | Read Endpoint Links | - | 541 | Update Endpoint Links | - | 542 | Register a Group | - | 543 | Group Removal | - | 544 | Lookup | Find Items | 545 +-----------------------+-------------+ 547 Table 2: Mapping of Resource Directory Interactions to Bulletin Board 549 A.4. CoRE Mirror Server 551 Similar to a CoAP Publish-Subscribe Broker, a CoRE Mirror Server 552 [I-D.vial-core-mirror-server] allows a sleepy device to store 553 representations of their resources so that other devices can access 554 the representations while it is sleeping. 556 +----------------------------------+ 557 | ___ | 558 | / \ Bulletin Board | 559 | \___/ ___ | 560 | |___________/ \ Mirrored | 561 | | item \___/ Resource A | 562 | | ___ | 563 | |___________/ \ Mirrored | 564 | | item \___/ Resource B | 565 | | ___ | 566 | |___________/ \ Mirrored | 567 | item \___/ Resource C | 568 | | 569 +----------------------------------+ 571 Figure 7: A Bulletin Board Acting as a Mirror Server 573 +----------------------------+-------------+ 574 | Interaction | Mapped to | 575 +----------------------------+-------------+ 576 | Discovery | Discovery | 577 | Registration | Create Item | 578 | Removal | Delete Item | 579 | Update Mirrored Resource | Update Item | 580 | Retrieve Mirrored Resource | Read Item | 581 +----------------------------+-------------+ 583 Table 3: Mapping of Mirror Server Interactions to Bulletin Board 585 Author's Address 587 Klaus Hartke 588 Universitaet Bremen TZI 589 Postfach 330440 590 Bremen D-28359 591 Germany 593 Phone: +49-421-218-63905 594 Email: hartke@tzi.org