idnits 2.17.1 draft-shelby-core-resource-directory-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 (November 1, 2011) is 4554 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-06 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-06 == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-01 == Outdated reference: A later version (-05) exists of draft-vanderstok-core-bc-03 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft Sensinode 4 Intended status: Standards Track S. Krco 5 Expires: May 4, 2012 Ericsson 6 November 1, 2011 8 CoRE Resource Directory 9 draft-shelby-core-resource-directory-02 11 Abstract 13 In many M2M scenarios, direct discovery of resources is not practical 14 due to sleeping nodes, disperse networks, or networks where multicast 15 traffic is inefficient. These problems can be solved by employing an 16 entity called a Resource Directory (RD), which hosts descriptions of 17 resources held on other servers, allowing lookups to be performed for 18 those resources. This document specifies the web interfaces that a 19 Resource Directory supports in order for web servers to discover the 20 RD and to registrer, maintain, lookup and remove resources 21 descriptions. Furthermore, new link attributes useful in conjunction 22 with an RD are defined. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 4, 2012. 41 Copyright Notice 43 Copyright (c) 2011 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . . 4 61 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . . 5 62 3.2. Use Case: Home and Building Automation . . . . . . . . . . 6 63 4. Resource Directory Interfaces . . . . . . . . . . . . . . . . 6 64 4.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 8 66 4.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.4. Validation . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4.5. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 4.6. Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 14 70 5. New Link-Format Attributes . . . . . . . . . . . . . . . . . . 16 71 5.1. Resource Instance 'ins' attribute . . . . . . . . . . . . 16 72 5.2. Export 'exp' attribute . . . . . . . . . . . . . . . . . . 16 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 74 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 75 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 76 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 17 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 79 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 82 1. Introduction 84 The Constrained RESTful Environments (CoRE) working group aims at 85 realizing the REST architecture in a suitable form for the most 86 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 87 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 88 machine (M2M) applications such as smart energy and building 89 automation [I-D.shelby-core-coap-req]. 91 The discovery of resources offered by a constrained server is very 92 important in machine-to-machine applications where there are no 93 humans in the loop and static interfaces result in fragility. The 94 discovery of resources provided by an HTTP Web Server is typically 95 called Web Linking [RFC5988]. The use of Web Linking for the 96 description and discovery of resources hosted by constrained web 97 servers is specified by the CoRE Link Format 98 [I-D.ietf-core-link-format]. This specification however only 99 describes how to discover resources from the web server that hosts 100 them by requesting /.well-known/core. In many M2M scenarios, direct 101 discovery of resources is not practical due to sleeping nodes, 102 disperse networks, or networks where multicast traffic is 103 inefficient. These problems can be solved by employing an entity 104 called a Resource Directory (RD), which hosts descriptions of 105 resources held on other servers, allowing lookups to be performed for 106 those resources. 108 This document specifies the web interfaces that a Resource Directory 109 supports in order for web servers to discover the RD and to 110 registrer, maintain, lookup and remove resources descriptions. 111 Furthermore, new link attributes useful in conjunction with a 112 Resource Directory are defined. Although the examples in this 113 document show the use of these interfaces with CoAP 114 [I-D.ietf-core-coap], they may be applied in an equivalent manner to 115 HTTP [RFC2616]. 117 2. Terminology 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119]. 123 This specification requires readers to be familiar with all the terms 124 and concepts that are discussed in [RFC5988] and 125 [I-D.ietf-core-link-format]. Readers should also be familiar with 126 the terms and concepts discussed in [I-D.ietf-core-coap]. This 127 specification makes use of the following additional terminology: 129 Resource Directory 130 An web entity that stores information about web resources and 131 implements the REST interfaces defined in this specification for 132 registration and lookup of those resources. 134 Domain 135 In the context of a Resource Directory, a domain is a logical 136 grouping of end-points. All end-point within a domain MUST be 137 unique. 139 End-point 140 An end-point (EP) is a term used to describe a web server or 141 client in [I-D.ietf-core-coap]. In the context of this 142 specificaiton an end-point is used to describe a web server that 143 registers resources to the Resource Directory. During 144 registration the end-point is identified by a combination of the 145 Host and Instance fields. 147 Host 148 In the context of this specification, a Host name can be given to 149 the device that is registering. 151 Instance 152 In the context of this specification, the Instance is used when 153 registering to differentiate between multiple web servers running 154 on the same device. 156 3. Architecture and Use Cases 158 The resource directory architecture is shown in Figure 1. A Resource 159 Directory (RD) is used as a repository for Web Links [RFC5988] about 160 resources hosted on other web servers, which are called end-points 161 (EP). An end-point is a web server associated with a port, thus a 162 physical node may host one or more end-points. The RD implements a 163 set of REST interfaces for end-points to register and maintain sets 164 of Web Links (called resource directory entries), for the RD to 165 validate entries, and for clients to lookup resources from the RD. 166 End-points themselves can also act as clients. An RD can be 167 logically segmented by the use of Domains. The domain an end-point 168 is associated with can be defined by the RD, an outside entity or by 169 the EP during registration. 171 End-points are assumed to proactively register and maintain resource 172 directory entries on the RD, which are soft state and need to be 173 periodially refreshed. An EP is provided with interfaces to 174 register, update and remove a resource directory entry. Furthermore, 175 a mechanism to discover a RD using the CoRE Link Format is defined. 177 It is also possible for an RD to proactively discover Web Links from 178 EPs and add them as resource directory entries, or to validate 179 existing resource directory entries. A lookup interface for 180 discovering any of the Web Links held in the RD is provided using the 181 CoRE Link Format. 183 Registration Lookup 184 +----+ | | 185 | EP |---- | | 186 +----+ ---- | | 187 --|- +------+ | 188 +----+ | ----| | | +--------+ 189 | EP | ---------|-----| RD |----|-----| Client | 190 +----+ | ----| | | +--------+ 191 --|- +------+ | 192 +----+ ---- | | 193 | EP |---- | | 194 +----+ 196 Figure 1: The resource directory architecture. 198 3.1. Use Case: Cellular M2M 200 Over the last few years, mobile operators around the world have 201 focused on development of M2M solutions in order to expand the 202 business to the new type of users, i.e. machines. The machines are 203 connected directly to a mobile network using appropriate embedded air 204 interface (GSM/GPRS, WCDMA, LTE) or via a gateway providing short and 205 wide range wireless interfaces. From the system design point of 206 view, the ambition is to design horizontal solutions that can enable 207 utilization of machines in different applications depending on their 208 current availability and capabilities as well as application 209 requirements, thus avoiding silo like solutions. One of the crucial 210 enablers of such design is the ability to discover resources 211 (machines - End Points) capable of providing required information at 212 a given time or acting on instructions from the end users. 214 In a typical scenario, during a boot-up procedure (and periodically 215 afterwards), the machines (EPs) register with a Resource Directory 216 (for example EPs installed on vehicles enabling tracking of their 217 position for the fleet management purposes and monitoring environment 218 parameters) hosted by the mobile operator or somewhere else in the 219 network, submiting a description of own capabilities. Due to the 220 usual network configuration of mobile networks, the EPs attached to 221 the mobile network do not have routable addresses. Therefore, a 222 remote server is usually used to provide proxy access to the EPs. 224 The address of each (proxy) EP on this server is included in the 225 resource description stored in the RD. The users, for example mobile 226 applications for environment monitoring, contact the RD, look-up the 227 EPs capable of providing information about the environment using 228 appropriate set of tags, obtain information on how to contact them 229 (URLs of the proxy server) and then initate interaction to obtain 230 information that is finally processed, displayed on the screen and 231 usually stored in a database. Similarly, fleet management systems 232 provide a set of credentials along with the appropriate tags to the 233 RD to look-up for EPs deployed on the vehicles the application is 234 responsible for. 236 3.2. Use Case: Home and Building Automation 238 Home and commercial building automation systems can benefit from the 239 use of M2M web services. The use of CoRE in home automation across 240 multiple subnets is described in [I-D.brandt-coap-subnet-discovery] 241 and in commercial building automation in [I-D.vanderstok-core-bc]. 242 The discovery requirements of these applications are demanding. Home 243 automation usually relies on run-time discovery to commision the 244 system, whereas in building automation a combination of professional 245 commissioning and run-time discovery. Both home and building 246 automation involve peer-to-peer interactions between end-points, and 247 involve battery-powered sleeping devices. 249 The exporting of resource information to other discovery systems is 250 also important in these automation applications. In home automation 251 there is a need to interact with other consumer electronics, which 252 may already support DNS-SD, and in building automation larger 253 resource directories or DNS-SD covering multiple buildings. 255 4. Resource Directory Interfaces 257 This section defines the REST interfaces between an RD and end- 258 points, and a lookup interface between an RD and clients. Although 259 the examples throughout this section assume use of CoAP 260 [I-D.ietf-core-coap], these REST interfaces can also be realized 261 using HTTP [RFC2616]. An RD implementing this specification MUST 262 support the discovery, registration, update, removal and lookup 263 interfaces defined in this section and MAY support the validation 264 interface. For the purpose of validation, an end-point implementing 265 this specification SHOULD support Etag validation on /.well-known/ 266 core. 268 4.1. Discovery 270 Before an end-point can make use of an RD, it must first know its 271 location and optionally the path of the RD root resource. There can 272 be several mechanisms for discovering the RD including assuming a 273 default location (e.g. on an Edge Router in a LoWPAN), by assigning 274 an anycast address to the RD, using DHCP, or by discovering the RD 275 using the CoRE Link Format. This section defines discovery of the RD 276 using the well-known interface of the CoRE Link Format 277 [I-D.ietf-core-link-format] as the required mechanism. It is however 278 expected that RDs will also be discoverable via other methods 279 depending on the deployment. 281 Discovery is performed by sending either a multicast or unicast GET 282 request to /.well-known/core and including a Resource Type (rt) 283 parameter [I-D.ietf-core-link-format] with the value "core-rd" in the 284 query string. Upon success, the response will contain a payload with 285 a link format entry for each RD discovered, with the URL indicating 286 the root resource of the RD. When performing multicast discovery, 287 the multicast IP address used will depend on the scope required and 288 the multicast capabilities of the network (TBD if a specific 289 multicast address should be defined for RDs). 291 An RD implementing this specification MUST support query filtering 292 for the rt parameter as defined in [I-D.ietf-core-link-format]. 294 The discovery interface is specified as follows: 296 Interaction: EP -> RD 298 Path: /.well-known/core 300 Method: GET 302 Content-Type: application/link-format (if any) 304 Parameters: 306 Resource Type (rt): MUST contain the value "core-rd" 308 Instance (ins): Used to differentiate between multiple RDs. 310 Success: 2.05 "Content" with an application/link-format payload 311 containing a matching entry for the RD resource. 313 Failure: 2.05 "Content" (should be a "No Content" code?) with an 314 empty payload is returned in case no matching entry is found for a 315 unicast request. 317 Failure: No error response to a multicast request. 319 Failure: 4.00 "Bad Request" 321 The following example shows an end-point discovering an RD using this 322 interface, thus learning that the base RD resource is at /rd. Note 323 that it is up to the RD to choose its base RD resource. 325 End-point RD 326 | | 327 | ----- GET /.well-known/core?rt=core-rd ------> | 328 | | 329 | | 330 | <---- 2.05 Content "; rt="core-rd" ------ | 331 | | 333 Req: GET coap://[ff02::1]/.well-known/core?rt=core-rd 335 Res: 2.05 Content 336 ;rt="core-rd";ins="Primary" 338 4.2. Registration 340 After discovering the location of an RD, an end-point MAY register 341 its resources to the RD's registration interface. This interface 342 accepts a POST from an end-point containing the list of resources to 343 be added to the directory as the message payload in the CoRE Link 344 Format along with query string parameters indicating the name of the 345 end-point, an optional node identifier and the lifetime of the 346 registration. The end-point name is formed by concatenating the Host 347 and Instance parameters included with the registration. All 348 parameters of the registration are optional. In the absense of a 349 Host parameter, the RD will generate a unique one on behalf of the 350 end-point. The RD then creates a new resource or updates an existing 351 resource in the RD and returns its location. An end-point MUST use 352 that location when refreshing registrations using this interface. 353 End-point resources in the RD are kept active for the period 354 indicated by the lifetime parameter. The end-point is reponsible for 355 refreshing the entry within this period using either the registration 356 or update interface. 358 The registration interface is specified as follows: 360 Interaction: EP -> RD 362 Path: /.well-known/core or /{rd-base} 364 Method: POST 366 Content-Type: application/link-format 368 Etag: The Etag option MAY be included to allow an RD to perform 369 validation in the future. 371 Parameters: 373 Lifetime (lt): Lifetime of the registration in seconds. Range of 374 60-4294967295. If no lifetime is included, a default value of 375 86400 (24 hours) SHOULD be assumed. 377 Host (h): The host identifier or name of the registering node. 378 The maximum length of this parameter is 63 octets. This 379 parameter is combined with the Instance parameter (if any) to 380 form the end-point name. If not included, the RD MUST generate 381 a unique Host name on behalf of the node. 383 Instance (ins): The instance of the end-point on this host, if 384 there are more than one. The maximum length of this parameter 385 is 63 octets. Optional. 387 Type (rt): The semantic type of the end-point. The maximum 388 length of this parameter is 63 octets. Optional. 390 Domain (d): The domain to which this end-point belongs. The 391 maximum length of this parameter is 63 octets. Optional. 393 Context (con): This parameter sets the scheme, address and port 394 at which this server is available in the form 395 scheme://host:port. Optional. In the absence of this 396 parameter the scheme of the protocol, source IP address and 397 source port used to register are assumed. 399 Success: 2.01 "Created". The Location header MUST be included with 400 the new resource entry for the end-point. This Location SHOULD be 401 an stable identifier generated by the RD as it is used for all 402 subsequent operations on this registration (update, delete). 404 Failure: 4.00 "Bad Request". Malformed request. 406 Failure: 5.03 "Service Unavailable". Service could not perform the 407 operation. 409 The following example shows an end-point with the name "node1" 410 registering two resources to an RD using this interface. The 411 resulting location /rd/4521 is just an example of an RD generated 412 key. 414 End-point RD 415 | | 416 | --- POST /rd " | 417 | | 418 | | 419 | <-- 2.01 Created Location: /rd/4521 ---------- | 420 | | 422 Req: POST coap://rd.example.org/rd?h=node1<=1024 423 Etag: 0x3f 424 Payload: 425 ;ct=41;rt="TemperatureC";if="sensor", 426 ;ct=41;rt="LightLux";if="sensor" 428 Res: 2.01 Created 429 Location: /rd/4521 431 4.3. Update 433 The update interface is used by an end-point to refresh or update its 434 registration with an RD. To use the interface, the end-point sends a 435 PUT request to the resource returned in the Location option in the 436 response to the first registration. An update MAY contain 437 registraion parameters or a payload in CoRE Link Format if there have 438 been changes since the last registration or update. Paremeters that 439 have not changed SHOULD NOT be included in an update. 441 The update interface is specified as follows: 443 Interaction: EP -> RD 445 Path: Location returned by registration. 447 Method: PUT 449 Content-Type: application/link-format (if any) 451 Etag: The Etag option MAY be included to allow an RD to compare the 452 existing entry and perform validation in the future. 454 Parameters: 456 Lifetime (lt): Lifetime of the registration in seconds. Range of 457 60-4294967295. If no lifetime is included, a default value of 458 86400 (24 hours) SHOULD be assumed. 460 Host (h): The host identifier or name of the registering node. 461 The maximum length of this parameter is 63 octets. This 462 parameter is combined with the Instance parameter (if any) to 463 form the end-point name. If not included, the RD MUST generate 464 a unique Host name on behalf of the node. 466 Instance (ins): The instance of the end-point on this host, if 467 there are more than one. The maximum length of this parameter 468 is 63 octets. Optional. 470 Type (rt): The semantic type of the end-point. The maximum 471 length of this parameter is 63 octets. Optional. 473 Domain (d): The domain to which this end-point belongs. The 474 maximum length of this parameter is 63 octets. Optional. 476 Context (con): This parameter sets the scheme, address and port 477 at which this server is available in the form 478 scheme://host:port. Optional. In the absence of this 479 parameter the scheme of the protocol, source IP address and 480 source port used to register are assumed. 482 Success: 2.04 "Changed" in case the resource and/or lifetime was 483 successfully updated 485 Failure: 4.00 "Bad Request". Malformed request. 487 Failure: 5.03 "Service Unavailable". Service could not perform the 488 operation. 490 The following example shows an end-point updating a new set of 491 resources to an RD using this interface. 493 End-point RD 494 | | 495 | --- PUT /rd/4521 " | 496 | | 497 | | 498 | <-- 2.04 Changed ---------------------------- | 499 | | 501 Req: PUT /rd/4521 502 Etag: 0x40 503 Payload: 504 ;ct=41;ins="Indoor";rt="TemperatureC";if="sensor", 505 ;ct=41;ins="Outdoor";rt="TemperatureC";if="sensor", 506 ;ct=41;rt="LightLux";if="sensor" 508 Res: 2.04 Changed 510 4.4. Validation 512 In some cases, an RD may want to validate that it has the latest 513 version of an end-point's resource. This can be performed with a GET 514 on the well-known interface of the CoRE Link Format including the 515 latest Etag stored for that end-point. For the purpose of 516 validation, an end-point implementing this specification SHOULD 517 support Etag validation on /.well-known/core. 519 The validation interface is specified as follows: 521 Interaction: RD -> EP 523 Path: /.well-known/core 525 Method: GET 527 Content-Type: application/link-format (if any) 529 Etag: The Etag option MUST be included 531 Parameters: None 533 Success: 2.03 "Valid" in case the Etag matches 535 Success: 2.05 "Content" in case the Etag does not match, the 536 response MUST include the most recent resource representation and 537 its corresponding Etag. 539 Failure: 4.00 "Bad Request". Malformed request. 541 The following examples shows a successful validation. 543 End-point RD 544 | | 545 | <--- GET /.well-known/core Etag: 0x40 -------- | 546 | | 547 | | 548 | --- 2.03 Valid -----------------------------> | 549 | | 551 Req: GET /.well-known/core 552 Etag: 0x40 554 Res: 2.03 Valid 556 4.5. Removal 558 Although RD entries have soft state and will eventually timeout after 559 their lifetime, an end-point SHOULD explicitly remove its entry from 560 the RD if it knows it will no longer be available (for example on 561 shut-down). This is accomplished using a removal interface on the RD 562 by performing a DELETE on the end-point resource. 564 The removal interface is specified as follows: 566 Interaction: EP -> RD 568 Path: Location returned by registration. 570 Method: DELETE 572 Content-Type: None 574 Parameters: None 576 Success: 2.02 "Deleted" upon successful deletion 578 Failure: 4.00 "Bad Request". Malformed request. 580 Failure: 5.03 "Service Unavailable". Service could not perform the 581 operation. 583 The following examples shows successful removal of the end-point from 584 the RD. 586 End-point RD 587 | | 588 | --- DELETE /rd/4521 ------------------------> | 589 | | 590 | | 591 | <-- 2.02 Deleted ---------------------------- | 592 | | 594 Req: DELETE /rd/4521 596 Res: 2.02 Deleted 598 4.6. Lookup 600 In order for an RD to be used for discovering resources registered 601 with it, a lookup interface is provided. This lookup interface is 602 provided as a default, and it is assumed that RDs may also support 603 lookups to return resource descriptions in alternative formats (e.g. 604 Atom or HTML Link) or using more advanced interfaces (e.g. supporting 605 context or semantic based lookup). 607 The lookup interface is provided using the CoRE Link Format 608 [I-D.ietf-core-link-format] resource discovery mechanism on the root 609 RD resource (/rd in the examples). The scope of the discovery is 610 controlled by the End-point (ep=) and Domain (d=) parameters. A 611 lookup on the root RD resource /rd queries all resources on the RD, a 612 lookup /rd?d=domain lists all resources in a domain and a lookup 613 /rd?ep=end-point performs a lookup on resources associated with that 614 end-point. 616 An RD SHOULD support the query filtering defined in 617 [I-D.ietf-core-link-format] to allow for filtered lookups. To 618 optimize the size of a lookup response, any non-wildcard attributes 619 in the query string SHOULD NOT be included in the resulting links. 621 The lookup interface is specified as follows: 623 Interaction: Client -> RD 625 Path: /{rd-base}, e.g. /rd 626 Method: GET 628 Content-Type: application/link-format (if any) 630 Parameters: 632 End-point (ep): The end-point (concatenation of host and ins 633 parameters used in registration) from which resources should be 634 looked up. 636 Domain (d): The domain from which resources should be looked up. 637 The maximum length of this parameter is 63 octets. Optional. 639 Filtering: CoRE Link Format attributes may be included to further 640 filter the lookup. 642 Success: 2.05 "Content" with an application/link-format payload 643 containing a matching entries for the lookup. 645 Failure: 4.04 "Not Found" in case no matching entry is found for a 646 unicast request. 648 Failure: No error response to a multicast request. 650 Failure: 4.00 "Bad Request". Malformed request. 652 Failure: 5.03 "Service Unavailable". Service could not perform the 653 operation. 655 The following example shows a client performing a lookup on an RD 656 using this interface. 658 Client RD 659 | | 660 | ----- GET /rd?rt=Temperature ----------------------------> | 661 | | 662 | | 663 | <-- 2.05 Content ";rt="Temperature" ---- | 664 | | 666 Req: GET /rd?rt=Temperature 668 Res: 2.05 Content 669 ;rt="Temperature" 671 5. New Link-Format Attributes 673 When using the CoRE Link Format to describe resources being 674 discovered by or posted to a resource directory service, additional 675 information about those resources is useful. This specification 676 defines the following new attributes for use in the CoRE Link Format 677 [I-D.ietf-core-link-format]: 679 link-extension = ( "ins" "=" quoted-string ) ; Max 63 octets 680 link-extension = ( "exp" ) 682 5.1. Resource Instance 'ins' attribute 684 The Resource Instance "ins" attribute is an identifier for this 685 resource, which makes it possible to distinguish from other similar 686 resources. This attribute is similar in use to the "Instance" 687 portion of a DNS-SD record, and SHOULD be unique across resources 688 with the same Resource Type attribute in the domain it is used. A 689 Resource Instance might be a descriptive string like "Ceiling Light, 690 Room 3", a short ID like "AF39" or a unique UUID or iNumber. This 691 attribute is used by a Resource Directory to distinguish between 692 multiple instances of the same resource type within a system. 694 This attribute MUST be no more than 63 octets in length. The 695 resource identifier attribute MUST NOT appear more than once in a 696 link description. 698 5.2. Export 'exp' attribute 700 The Export "exp" attribute is used as a flag to indicate that a link 701 description MAY be exported by a resource directory to external 702 directories. 704 The CoRE Link Format is used for many purposes between CoAP end- 705 points. Some are useful mainly locally, for example checking the 706 observability of a resource before accessing it, determining the size 707 of a resource, or traversing dynamic resource structures. However, 708 other links are very useful to be exported to other directories, for 709 example the entry point resource to a functional service. 711 6. Security Considerations 713 This document needs the same security considerations as described in 714 Section 7 of [RFC5988] and Section 6 of [I-D.ietf-core-link-format]. 715 The /.well-known/core resource may be protected e.g. using DTLS when 716 hosted on a CoAP server as described in [I-D.ietf-core-coap]. 718 7. IANA Considerations 720 "core-rd" resource type needs to be registered if an appropriate 721 registry is created. 723 "ins" and "exp" attributes need to be registered when a future Web 724 Linking attribute is created. 726 8. Acknowledgments 728 Szymon Sasin, Carsten Bormann, Kerry Lynn, Peter van der Stok, Anders 729 Brandt, Matthieu Vial and Linyi Tian have provided helpful comments, 730 discussions and ideas to improve and shape this document. The 731 authors would also like to thank their collagues from the EU FP7 732 SENSEI project, where many of the resource directory concepts were 733 originally developed. 735 9. Changelog 737 Changes from -01 to -02: 739 o Added a terminology section. 741 o Changed the inclusing of an Etag in registration or update to a 742 MAY. 744 o Added the concept of an RD domain and a registration parameter 745 for it. 747 o Recommended the Location returned from a registration to be 748 stable, allowing for end-point and domain information to be 749 changed during updates. 751 o Changed the lookup interface to accept end-point and domain as 752 query string parameters to control the scope of a lookup. 754 10. References 755 10.1. Normative References 757 [I-D.ietf-core-link-format] 758 Shelby, Z., "CoRE Link Format", 759 draft-ietf-core-link-format-06 (work in progress), 760 June 2011. 762 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 763 Requirement Levels", BCP 14, RFC 2119, March 1997. 765 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 767 10.2. Informative References 769 [I-D.brandt-coap-subnet-discovery] 770 Brandt, A., "Discovery of CoAP servers across subnets", 771 draft-brandt-coap-subnet-discovery-00 (work in progress), 772 March 2011. 774 [I-D.ietf-core-coap] 775 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 776 "Constrained Application Protocol (CoAP)", 777 draft-ietf-core-coap-06 (work in progress), May 2011. 779 [I-D.shelby-core-coap-req] 780 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 781 Kelsey, "CoAP Requirements and Features", 782 draft-shelby-core-coap-req-01 (work in progress), 783 April 2010. 785 [I-D.vanderstok-core-bc] 786 Stok, P. and K. Lynn, "CoAP Utilization for Building 787 Control", draft-vanderstok-core-bc-03 (work in progress), 788 March 2011. 790 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 791 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 792 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 794 Authors' Addresses 796 Zach Shelby 797 Sensinode 798 Kidekuja 2 799 Vuokatti 88600 800 FINLAND 802 Phone: +358407796297 803 Email: zach@sensinode.com 805 Srdjan Krco 806 Ericsson 808 Phone: 809 Email: srdjan.krco@ericsson.com