idnits 2.17.1 draft-hartke-t2trg-coral-reef-03.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 (November 4, 2019) is 1635 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'I-D.hartke-t2trg-coral-reef' is mentioned on line 978, but not defined == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-01 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-23 Summary: 0 errors (**), 0 flaws (~~), 4 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 Ericsson 4 Intended status: Experimental November 4, 2019 5 Expires: May 7, 2020 7 Resource Discovery in Constrained RESTful Environments (CoRE) 8 using the Constrained RESTful Application Language (CoRAL) 9 draft-hartke-t2trg-coral-reef-03 11 Abstract 13 This document explores how the Constrained RESTful Application 14 Language (CoRAL) might be used for two use cases in Constrained 15 RESTful Environments (CoRE): CoRE Resource Discovery, which allows a 16 client to discover the resources of a server given a host name or IP 17 address, and CoRE Resource Directory, which provides a directory of 18 resources on many servers. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 7, 2020. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Resource Discovery . . . . . . . . . . . . . . . . . . . 4 57 2.2. Resource Directory . . . . . . . . . . . . . . . . . . . 5 58 2.3. Notational Conventions . . . . . . . . . . . . . . . . . 7 59 3. Resource Metadata . . . . . . . . . . . . . . . . . . . . . . 7 60 4. Resource Discovery . . . . . . . . . . . . . . . . . . . . . 8 61 4.1. Well-known Resource . . . . . . . . . . . . . . . . . . . 9 62 4.1.1. Resource List Representation . . . . . . . . . . . . 9 63 4.2. Interactions . . . . . . . . . . . . . . . . . . . . . . 10 64 4.2.1. Getting All Resources . . . . . . . . . . . . . . . . 10 65 4.2.2. Getting Resources By Resource Type . . . . . . . . . 11 66 4.2.3. Getting Resources By Interface Type . . . . . . . . . 12 67 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 13 68 5.1. Resource Lookups . . . . . . . . . . . . . . . . . . . . 13 69 5.1.1. Filter Query Representation . . . . . . . . . . . . . 13 70 5.2. Resource Registrations . . . . . . . . . . . . . . . . . 13 71 5.2.1. Registration Unit Representation . . . . . . . . . . 13 72 5.2.2. Registration Unit List Representation . . . . . . . . 14 73 5.3. Interactions . . . . . . . . . . . . . . . . . . . . . . 15 74 5.3.1. Getting All Resources . . . . . . . . . . . . . . . . 15 75 5.3.2. Getting Resources By Resource Type . . . . . . . . . 16 76 5.3.3. Getting Resources By Interface Type . . . . . . . . . 17 77 5.3.4. Getting Resources By Resource Metadata . . . . . . . 18 78 5.3.5. Getting All Registration Units . . . . . . . . . . . 19 79 5.3.6. Creating a Registration Unit . . . . . . . . . . . . 20 80 5.3.7. Reading a Registration Unit . . . . . . . . . . . . . 21 81 5.3.8. Updating a Registration Unit . . . . . . . . . . . . 22 82 5.3.9. Deleting a Registration Unit . . . . . . . . . . . . 23 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 24 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 85 7.1. CoRE Dictionary . . . . . . . . . . . . . . . . . . . . . 24 86 7.2. CoAP Content Format . . . . . . . . . . . . . . . . . . . 26 87 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 88 8.1. Normative References . . . . . . . . . . . . . . . . . . 26 89 8.2. Informative References . . . . . . . . . . . . . . . . . 27 90 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 28 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 28 93 1. Preamble 95 This document explores how CoRE Resource Discovery [RFC6690] and CoRE 96 Resource Directory [I-D.ietf-core-resource-directory] might look like 97 if based on CoRAL [I-D.ietf-core-coral]. The exploration is done in 98 the style of a self-contained specification rather than a description 99 of changes. 101 This document doesn't represent a proposal or recommendation for 102 standardization at its current stage. 104 2. Introduction 106 Constrained RESTful Environments (CoRE) realize the Representational 107 State Transfer (REST) architectural style [REST] in a suitable form 108 for constrained nodes (e.g., 8-bit microcontrollers with limited RAM 109 and ROM) and constrained networks [RFC7228]. CoRE technologies like 110 the Constrained Application Protocol (CoAP) [RFC7252] are aimed at 111 machine-to-machine (M2M) applications like smart energy and building 112 automation. 114 The discovery of resources hosted by a constrained server is very 115 important in machine-to-machine applications where no humans are in 116 the loop and static interfaces result in fragility. In the Web, the 117 discovery of resources provided by a Web server is typically based on 118 links in representations of resources pointing at other resources, 119 with search engines providing an entry point to find resources based 120 on queries. 122 This document applies the idea of using Web Linking [RFC8288] for 123 discovery to Constrained RESTful Environments. The discovery of 124 resources hosted by a constrained Web server, resource metadata, and 125 related resources is called "CoRE Resource Discovery". 127 The main function of CoRE Resource Discovery is to provide Uniform 128 Resource Identifiers (URIs) [RFC3986] for the resources hosted by a 129 server, complemented by metadata about those resources and possibly 130 links to further resources. In this document, this information is 131 conveyed in the Constrained RESTful Application Language (CoRAL) 132 [I-D.ietf-core-coral]. 134 This document specifies the use of CoRAL in two use cases: 136 Resource Discovery 138 Allows a client to discover the resources of a server, given a 139 server's host name or IP address. 141 Resource Directory 143 Allows a client to discover the resources of several servers, 144 given a resource directory's URL. 146 Allows a server (or a third party acting on behalf of a server) to 147 register its resources with a resource directory, given a resource 148 directory's URL. 150 2.1. Resource Discovery 152 In many M2M applications, such as home or building automation, there 153 is a need for local clients and servers to find and interact with 154 each other without human intervention. CoRE Resource Discovery can 155 be used by clients in such environments to discover the resources 156 hosted by the server given a host name or IP address. 158 In this specification, the discovery is performed by retrieving a 159 CoRAL representation of a well-known resource on the server, called 160 "/.well-known/core". The representation contains a list of links to 161 the resources of interest on the server, which are typically entry 162 points to the different applications hosted by the server. The link 163 targets may be annotated with resource metadata. A client would then 164 find an appropriate resource based on the metadata. Queries based on 165 metadata may also be specified in the query string to filter the 166 result set. 168 The following example shows a client discovering the resources of a 169 CoAP server by making a GET request to the "/.well-known/core" 170 resource. The client gets a 2.05 (Content) response with a list of 171 links of type to the resources on 172 the server. The links themselves contain metadata about the 173 resources (such as resource type, interface description, available 174 content formats, or even further links to other related resources). 176 => 0.01 GET 177 Uri-Path: .well-known 178 Uri-Path: core 179 Accept: TBD3 181 <= 2.05 Content 182 Content-Format: TBD3 184 #using 185 #using base = 186 #using iana = 188 rd-item { 189 ct 40 190 base:title "Sensor Index" 191 } 192 rd-item { 193 rt "temperature-c" 194 if "sensor" 195 iana:describedby 196 iana:alternate 197 } 198 rd-item { 199 rt "light-lux" 200 if "sensor" 201 } 203 The example contains links to three resources of interest on the 204 server: , , and . For 205 , a content format hint ("ct") and a title ("title") are 206 provided as resource metadata. For both and 207 , a resource type ("rt") and an interface description 208 ("if") are provided. Additionally, two links are provided with 209 further detail on : one to a schema describing this 210 resource ("describedby") and one to an substitute ("alternate"). 212 Common resource metadata are specified in Section 3. The "/.well- 213 known/core" resource and its interface are specified in Section 4. 215 2.2. Resource Directory 217 In many deployment scenarios, such as in constrained networks with 218 sleeping servers or in large M2M deployments with bandwidth limited 219 access networks, it is beneficial to deploy resource directory 220 entities that store links to resources stored on other servers. A 221 resource directory can be thought of as a limited search engine for 222 M2M resources. 224 In this specification, a resource directory provides the same lookup 225 interface as a "/.well-known/core" resource, except that it provides 226 links to resources on potentially many, many different servers. 227 Whereas a "/.well-known/core" resource is populated by the hosting 228 server, the resource directory provides a registration interface that 229 allows any server (or third party acting on behalf of a server) to 230 register its resources. 232 The registration interface is a collection resource with the common 233 operations of create, read, update, and delete. The items of the 234 collection are groups of links of type that are to be made available in the lookup interface. 237 The following example shows a client registering a group of links 238 with a resource directory by making a POST request to the collection 239 resource. The client receives a 2.01 (Created) response with the 240 location of the created collection item. The client can later use 241 this location to update or delete the whole group of links at once. 243 => 0.02 POST 244 Uri-Path: path 245 Uri-Path: to 246 Uri-Path: resource 247 Uri-Path: directory 248 Uri-Path: registrations 249 Content-Format: TBD3 251 #using 253 #base 254 rd-item { rt "light-lux" ct 0 } 255 rd-item { rt "light-lux" ct 0 } 256 rd-item { rt "light-lux" ct 0 } 258 <= 2.01 Created 259 Location-Path: path 260 Location-Path: to 261 Location-Path: resource 262 Location-Path: directory 263 Location-Path: registrations 264 Location-Path: 42 266 The following example shows a client performing a lookup on the 267 resource directory by making a GET request to the resource directory 268 resource. The client receives a 2.05 (Content) response with a 269 combined view of all groups of links registered earlier, filtered by 270 a query. 272 => 0.01 GET 273 Uri-Path: path 274 Uri-Path: to 275 Uri-Path: resource 276 Uri-Path: directory 277 Uri-Path: lookup 278 Uri-Query: rt=light-lux 279 Accept: TBD3 281 <= 2.05 Content 282 Content-Format: TBD3 284 #using 286 #base 287 rd-item { rt "light-lux" } 289 #base 290 rd-item { rt "light-lux" ct 0 } 291 rd-item { rt "light-lux" ct 0 } 292 rd-item { rt "light-lux" ct 0 } 294 The resource directory and its lookup and registration interface are 295 specified in Section 5. 297 2.3. Notational Conventions 299 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 300 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 301 "OPTIONAL" in this document are to be interpreted as described in BCP 302 14 [RFC2119] [RFC8174] when, and only when, they appear in all 303 capitals, as shown here. 305 3. Resource Metadata 307 Both "/.well-known/core" resources and resource directories link to 308 resources of interest using the 309 link relation type. Metadata for these resources can be expressed by 310 nesting the metadata inside these links. 312 In particular, resource metadata takes the shape of nested links that 313 either directly specify a literal value (such as a string or number) 314 or target a related resource identified by a URI; see Section 2.3 of 315 [I-D.ietf-core-coral] for details. 317 The following link relation types for expressing resource metadata 318 are defined: 320 321 The link target is a hint indicating what the (human-spoken) 322 language of the result of dereferencing the link context should 323 be. 325 326 The link target indicates the intended destination medium or media 327 for style information for the link context. 329 330 The link target is a label that it can be used as a human-readable 331 identifier for the link context. 333 Multiple labels can be specified, each as a link with the label as 334 link target. Each link can have a nested link indicating a 335 language tag for the label. 337 338 The link target is a hint indicating what the content format of 339 the result of dereferencing the link context should be. 341 342 The link target is an application-specific semantic type of the 343 link context. 345 Multiple resource types can be specified, each as a link with the 346 resource type as link target. The link target MUST NOT contain 347 multiple resource types separated by white space. 349 350 The link target is a specific interface definition that can be 351 used to interact with the link context. 353 354 The link target is an indication of the maximum size of the 355 resource representation returned by performing a GET on the link 356 context. 358 359 The link target is a hint about the Content-Formats that the link 360 context returns. 362 4. Resource Discovery 364 Given a host name or IP address, a client can discover the resources 365 of a server implementing this section through the use of a well-known 366 resource [RFC8615]. Well-known resources have a path component that 367 begins with "/.well-known/". This specification defines a new well- 368 known resource for CoRE Resource Discovery: "/.well-known/core". 370 4.1. Well-known Resource 372 The "/.well-known/core" resource is offered by servers implementing 373 this specification on the default port appropriate for the protocol 374 for the purpose of resource discovery. It is up to the server to 375 decide which of the resources in its namespace are included; the 376 "/.well-known/core" resource is generally meant to provide entry 377 points to applications hosted by the server. 379 A client wishing to discover the resources of a server constructs the 380 URI <{scheme}://{host}:{port}/.well-known/core> from the scheme, host 381 name/IP address, and port. The client then retrieves a CoRAL 382 document from this URI, as specified in [I-D.ietf-core-coral]. The 383 document contains a list of links, each from the well-known resource 384 to one resource hosted by the server, along with resource metadata. 385 The client can filter the list using a number of query parameters. 387 4.1.1. Resource List Representation 389 A list of resources is represented as a CoRAL document 390 [I-D.ietf-core-coral] containing the following elements: 392 o For each resource that the server wishes to advertise to the 393 client, a link of type 394 targeting that resource. The link MUST target a resource in the 395 namespace of the server (same origin). The link MAY have nested 396 links providing resource metadata (including, but not limited to, 397 the resource metadata specified in Section 3). 399 4.2. Interactions 401 4.2.1. Getting All Resources 403 A client can get a list of all resources by making a GET request to 404 <{scheme}://{host}:{port}/.well-known/core>. The request MUST 405 include an Accept option with value TBD3. 407 On success, the server returns a 2.05 (Content) response with a 408 representation of the list of resources (see Section 4.1.1) that the 409 server wishes to advertise to the client. 411 Example: 413 => 0.01 GET 414 Uri-Path: .well-known 415 Uri-Path: core 416 Accept: TBD3 418 <= 2.05 Content 419 Content-Format: TBD3 421 #using 422 #using base = 423 #using iana = 425 rd-item { 426 ct 40 427 base:title "Sensor Index" 428 } 429 rd-item { 430 rt "temperature-c" 431 if "sensor" 432 iana:describedby 433 iana:alternate 434 } 435 rd-item { 436 rt "light-lux" 437 if "sensor" 438 } 440 4.2.2. Getting Resources By Resource Type 442 A client can filter a list of resources by resource type by making a 443 GET request to <{scheme}://{host}:{port}/.well-known/ 444 core?rt={value}>. The request MUST include an Accept option with 445 value TBD3. 447 On success, the server returns a 2.05 (Content) response with a 448 representation of the list of resources (see Section 4.1.1), but 449 containing only the subset of links that has resource metadata of 450 type with the specified text value. 452 Example: 454 => 0.01 GET 455 Uri-Path: .well-known 456 Uri-Path: core 457 Uri-Query: rt=temperature-c 458 Accept: TBD3 460 <= 2.05 Content 461 Content-Format: TBD3 463 #using 464 #using iana = 466 rd-item { 467 rt "temperature-c" 468 if "sensor" 469 iana:describedby 470 iana:alternate 471 } 473 4.2.3. Getting Resources By Interface Type 475 A client can filter a list of resources by interface type by making a 476 GET request to <{scheme}://{host}:{port}/.well-known/ 477 core?if={value}>. The request MUST include an Accept option with 478 value TBD3. 480 On success, the server returns a 2.05 (Content) response with a 481 representation of the list of resources (see Section 4.1.1), but 482 containing only the subset of links that has resource metadata of 483 type with the specified text value. 485 Example: 487 => 0.01 GET 488 Uri-Path: .well-known 489 Uri-Path: core 490 Uri-Query: if=sensor 491 Accept: TBD3 493 <= 2.05 Content 494 Content-Format: TBD3 496 #using 497 #using iana = 499 rd-item { 500 rt "temperature-c" 501 if "sensor" 502 iana:describedby 503 iana:alternate 504 } 505 rd-item { 506 rt "light-lux" 507 if "sensor" 508 } 510 5. Resource Directory 512 A resource directory provides information about entry points to 513 applications hosted by other servers. It is intended to make 514 discovery operations more efficient than retrieving each "/.well- 515 known/core" of these servers individually. 517 5.1. Resource Lookups 519 A client wishing to discover resources using a resource directory 520 needs to be pre-configured with the URI of a resource directory or 521 acquire the URI through some discovery process. The client then 522 retrieves a CoRAL document from this URI, as specified in 523 [I-D.ietf-core-coral]. The document contains a list of links, each 524 from the resource directory to one of the resources in the directory, 525 along with any registered resource metadata. The client can filter 526 the list either by using a number of query parameters or by 527 submitting a filter query. 529 5.1.1. Filter Query Representation 531 TODO. 533 5.2. Resource Registrations 535 A server (or a third party acting on behalf of a server) can register 536 resources with a resource directory by submitting a CoRAL document, 537 containing the new links to be created at the directory. The 538 directory processes the submitted links in two ways: First, it 539 includes those links in the list of results to client queries. 540 Second, it creates a resource containing the group of submitted 541 links, such that the server (or third party) can easily update or 542 delete the whole group as a single unit at a later time. 544 5.2.1. Registration Unit Representation 546 A registration unit is represented as a CoRAL document 547 [I-D.ietf-core-coral] containing the registered resources as top- 548 level element. 550 A registered resource is represented as a link where the link 551 relation type is and the link 552 target is the registered resource. This link MAY have metadata about 553 the resource (including, but not limited to, of the type specified in 554 Section 3) as nested elements. 556 5.2.2. Registration Unit List Representation 558 A list of registration units is represented as a CoRAL document 559 [I-D.ietf-core-coral] containing the units in the list as top-level 560 elements. 562 Each registration unit is represented as a link where the link 563 relation type is and the link 564 target is the registration unit URI. 566 5.3. Interactions 568 5.3.1. Getting All Resources 570 A client can get a list of all resources by making a GET request to 571 the lookup URI. 573 On success, the server returns a 2.05 (Content) response with a 574 representation of the list of resources (see Section 4.1.1). 576 Example: 578 => 0.01 GET 579 Uri-Path: path 580 Uri-Path: to 581 Uri-Path: resource 582 Uri-Path: directory 583 Uri-Path: lookup 584 Accept: TBD3 586 <= 2.05 Content 587 Content-Format: TBD3 589 #using 590 #using base = 591 #using iana = 593 rd-item { 594 ct 40 595 base:title "Sensor Index" 596 } 597 rd-item { 598 rt "temperature-c" 599 if "sensor" 600 iana:describedby 601 iana:alternate 602 } 603 rd-item { 604 rt "light-lux" 605 if "sensor" 606 } 608 5.3.2. Getting Resources By Resource Type 610 A client can filter a list of resources by resource type by making a 611 GET request to the result of resolving relative to the 612 lookup URI. 614 On success, the server returns a 2.05 (Content) response with a 615 representation of the list of resources (see Section 4.1.1), but 616 containing only the subset of links that has resource metadata of 617 type with the specified text value. 619 Example: 621 => 0.01 GET 622 Uri-Path: path 623 Uri-Path: to 624 Uri-Path: resource 625 Uri-Path: directory 626 Uri-Path: lookup 627 Uri-Query: rt=temperature-c 628 Accept: TBD3 630 <= 2.05 Content 631 Content-Format: TBD3 633 #using 634 #using iana = 636 rd-item { 637 rt "temperature-c" 638 if "sensor" 639 iana:describedby 640 iana:alternate 641 } 643 5.3.3. Getting Resources By Interface Type 645 A client can filter a list of resources by interface type by making a 646 GET request to the result of resolving relative to the 647 lookup URI. 649 On success, the server returns a 2.05 (Content) response with a 650 representation of the list of resources (see Section 4.1.1), but 651 containing only the subset of links that has resource metadata of 652 type with the specified text value. 654 Example: 656 => 0.01 GET 657 Uri-Path: path 658 Uri-Path: to 659 Uri-Path: resource 660 Uri-Path: directory 661 Uri-Path: lookup 662 Uri-Query: if=sensor 663 Accept: TBD3 665 <= 2.05 Content 666 Content-Format: TBD3 668 #using 669 #using iana = 671 rd-item { 672 rt "temperature-c" 673 if "sensor" 674 iana:describedby 675 iana:alternate 676 } 677 rd-item { 678 rt "light-lux" 679 if "sensor" 680 } 682 5.3.4. Getting Resources By Resource Metadata 684 A client can filter a list of resources by submitting the 685 representation of a metadata filter (see Section 5.1.1) in a FETCH 686 request to the lookup URI. 688 On success, the server returns a 2.05 (Content) response with a 689 representation of the list of resources (see Section 4.1.1) that 690 match the filter. 692 Example: 694 => 0.05 FETCH 695 Uri-Path: path 696 Uri-Path: to 697 Uri-Path: resource 698 Uri-Path: directory 699 Uri-Path: lookup 700 Content-Format: TODO 701 Accept: TBD3 703 TODO 705 <= 2.05 Content 706 Content-Format: TBD3 708 #using 709 #using iana = 711 rd-item { 712 rt "temperature-c" 713 if "sensor" 714 iana:describedby 715 iana:alternate 716 } 718 5.3.5. Getting All Registration Units 720 A client can list a collection of registration units by making a GET 721 request to the collection URI. 723 On success, the server returns a 2.05 (Content) response with a 724 representation of the list of all registration units (see 725 Section 5.2.2) in the collection. 727 Example: 729 => 0.01 GET 730 Uri-Path: path 731 Uri-Path: to 732 Uri-Path: resource 733 Uri-Path: directory 734 Uri-Path: registrations 735 Accept: TBD3 737 <= 2.05 Content 738 Content-Format: TBD3 740 #using 742 rd-unit <./1> 743 rd-unit <./2> 744 rd-unit <./3> 745 rd-unit <./4> 747 5.3.6. Creating a Registration Unit 749 A client can add a new registration unit to a collection of 750 registration units by submitting a representation of the unit (see 751 Section 5.2.1) in a POST request to the registration collection URI. 753 On success, the server returns a 2.01 (Created) response indicating 754 the registration unit URI of the new registration unit. 756 Example: 758 => 0.02 POST 759 Uri-Path: path 760 Uri-Path: to 761 Uri-Path: resource 762 Uri-Path: directory 763 Uri-Path: registrations 764 Content-Format: TBD3 766 #base 767 rd-item { rt "light" ct 0 } 768 rd-item { rt "light" ct 0 } 769 rd-item { rt "light" ct 0 } 771 <= 2.01 Created 772 Location-Path: path 773 Location-Path: to 774 Location-Path: resource 775 Location-Path: directory 776 Location-Path: registrations 777 Location-Path: 42 779 5.3.7. Reading a Registration Unit 781 A client can read a registration unit by making a GET request to the 782 registration unit URI. 784 On success, the server returns a 2.05 (Content) response with a 785 representation of the registration unit (see Section 5.2.1). 787 Example: 789 => 0.01 GET 790 Uri-Path: path 791 Uri-Path: to 792 Uri-Path: resource 793 Uri-Path: directory 794 Uri-Path: registrations 795 Uri-Path: 42 796 Accept: TBD3 798 <= 2.05 Content 799 Content-Format: TBD3 801 #base 802 rd-item { rt "light" ct 0 } 803 rd-item { rt "light" ct 0 } 804 rd-item { rt "light" ct 0 } 806 5.3.8. Updating a Registration Unit 808 A client can update a resource registration by submitting the 809 representation of the updated registration (see Section 5.2.1) in a 810 PUT request to the topic URI. Any existing registrations in the 811 registration unit are replaced by this update. 813 On success, the server returns a 2.04 (Updated) response. 815 Example: 817 => 0.03 PUT 818 Uri-Path: path 819 Uri-Path: to 820 Uri-Path: resource 821 Uri-Path: directory 822 Uri-Path: registrations 823 Uri-Path: 42 824 Content-Format: TBD3 826 #base 827 rd-item { rt "light" ct 0 } 828 rd-item { rt "light" ct 0 } 830 <= 2.04 Changed 832 5.3.9. Deleting a Registration Unit 834 A client can delete a registration unit by making a DELETE request on 835 the registration unit URI. 837 On success, the server returns a 2.02 (Deleted) response. 839 Example: 841 => 0.04 DELETE 842 Uri-Path: path 843 Uri-Path: to 844 Uri-Path: resource 845 Uri-Path: directory 846 Uri-Path: registrations 847 Uri-Path: 42 849 <= 2.02 Deleted 851 6. Security Considerations 853 TODO. 855 7. IANA Considerations 857 7.1. CoRE Dictionary 859 This document creates a new registry named "CoRAL Dictionary for 860 CoRE" under the Constrained RESTful Environments (CoRE) Parameters" 861 registry [CORE-PARAMETERS] for use with the CoRAL binary format 862 [I-D.ietf-core-coral]. The registry is located at . 864 [[NOTE TO RFC EDITOR: Please replace all occurrences of 865 "http://TBD5/" in this document with the URI of the new registry.]] 867 The registry is a mapping between a key and a value. The key is an 868 integer in the range 0 to 2147483647 (2^31-1). The value is either 869 an Internationalized Resource Identifier (IRI) reference, a Boolean 870 value, an integer, a floating-point number, a date/time value, a byte 871 string, or a text string. Both the key and the value are to be 872 denoted in the CoRAL textual format [I-D.ietf-core-coral] and must be 873 unique within the registry. A reference may be provided to offer 874 more information about a value. 876 The registry policy is Expert Review. 878 The initial entries in the registry are as follows: 880 o Key: 0 881 Value: 882 Reference: [W3C.REC-rdf-schema-20140225] 884 o Key: 1 885 Value: 886 Reference: [RFC6573] 888 o Key: 2 889 Value: 890 Reference: [RFC6573] 892 o Key: 3 893 Value: 894 Reference: [I-D.ietf-core-coral] 896 o Key: 4 897 Value: 898 Reference: [I-D.ietf-core-coral] 900 o Key: 5 901 Value: 902 Reference: [I-D.ietf-core-coral] 904 o Key: 6 905 Value: 906 Reference: [I-D.ietf-core-coral] 908 o Key: 7 909 Value: 910 Reference: [I-D.ietf-core-coral] 912 o Key: 8 913 Value: 914 Reference: [I-D.hartke-t2trg-coral-reef] 916 o Key: 9 917 Value: 918 Reference: [I-D.hartke-t2trg-coral-reef] 920 o Key: 10 921 Value: 922 Reference: [I-D.ietf-core-coral] 924 o Key: 11 925 Value: 926 Reference: [I-D.hartke-t2trg-coral-reef] 928 o Key: 12 929 Value: 930 Reference: [I-D.ietf-core-coral] 932 o Key: 13 933 Value: 934 Reference: [I-D.ietf-core-coral] 936 o Key: 14 937 Value: 938 Reference: [I-D.hartke-t2trg-coral-reef] 940 o Key: 15 941 Value: 942 Reference: [I-D.hartke-t2trg-coral-reef] 944 o Key: 16 945 Value: 946 Reference: [I-D.hartke-t2trg-coral-reef] 948 o Key: 17 949 Value: 950 Reference: [I-D.hartke-t2trg-coral-reef] 952 o Key: 18 953 Value: 954 Reference: [I-D.hartke-t2trg-coral-reef] 956 o Key: 19 957 Value: 958 Reference: [I-D.ietf-core-coral] 960 o Key: 20 961 Value: "ltr" 962 Reference: 964 o Key: 21 965 Value: "rtl" 966 Reference: 968 7.2. CoAP Content Format 970 This document registers a CoAP content format for CoRAL documents in 971 the binary format that use the registry established in Section 7.1. 972 The registration is in accordance with the procedures of RFC 7252 973 [RFC7252]. 975 o Content Type: application/coral+cbor;dictionary="http://TBD5/" 976 Content Coding: identity 977 ID: TBD3 978 Reference: [I-D.hartke-t2trg-coral-reef] 980 [[NOTE TO RFC EDITOR: Please replace all occurrences of "TBD3" in 981 this document with the code point assigned by IANA.]] 983 [[NOTE TO IMPLEMENTERS: Experimental implementations can use content 984 format ID 65088 until IANA has assigned a code point.]] 986 8. References 988 8.1. Normative References 990 [I-D.ietf-core-coral] 991 Hartke, K., "The Constrained RESTful Application Language 992 (CoRAL)", draft-ietf-core-coral-01 (work in progress), 993 November 2019. 995 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 996 Requirement Levels", BCP 14, RFC 2119, 997 DOI 10.17487/RFC2119, March 1997, 998 . 1000 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1001 Application Protocol (CoAP)", RFC 7252, 1002 DOI 10.17487/RFC7252, June 2014, 1003 . 1005 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1006 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1007 May 2017, . 1009 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 1010 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 1011 . 1013 8.2. Informative References 1015 [CORE-PARAMETERS] 1016 IANA, "Constrained RESTful Environments (CoRE) 1017 Parameters", 1018 . 1020 [I-D.ietf-core-resource-directory] 1021 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1022 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1023 resource-directory-23 (work in progress), July 2019. 1025 [REST] Fielding, R., "Architectural Styles and the Design of 1026 Network-based Software Architectures", Ph.D. Dissertation, 1027 University of California, Irvine, 2000, 1028 . 1031 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1032 Resource Identifier (URI): Generic Syntax", STD 66, 1033 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1034 . 1036 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 1037 RFC 6573, DOI 10.17487/RFC6573, April 2012, 1038 . 1040 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1041 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1042 . 1044 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1045 Constrained-Node Networks", RFC 7228, 1046 DOI 10.17487/RFC7228, May 2014, 1047 . 1049 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1050 DOI 10.17487/RFC8288, October 2017, 1051 . 1053 [W3C.REC-rdf-schema-20140225] 1054 Brickley, D. and R. Guha, "RDF Schema 1.1", World Wide Web 1055 Consortium Recommendation REC-rdf-schema-20140225, 1056 February 2014, 1057 . 1059 Acknowledgements 1061 Thanks to Christian Amsuess and Carsten Bormann for helpful comments 1062 and discussions that have shaped the document. 1064 Author's Address 1066 Klaus Hartke 1067 Ericsson 1068 Torshamnsgatan 23 1069 Stockholm SE-16483 1070 Sweden 1072 Email: klaus.hartke@ericsson.com