draft-ietf-core-resource-directory-04.txt   draft-ietf-core-resource-directory-05.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft M. Koster Internet-Draft M. Koster
Intended status: Standards Track ARM Intended status: Standards Track ARM
Expires: January 7, 2016 C. Bormann Expires: April 18, 2016 C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
July 06, 2015 October 16, 2015
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-04 draft-ietf-core-resource-directory-05
Abstract Abstract
In many M2M applications, direct discovery of resources is not In many M2M applications, direct discovery of resources is not
practical due to sleeping nodes, disperse networks, or networks where practical due to sleeping nodes, disperse networks, or networks where
multicast traffic is inefficient. These problems can be solved by multicast traffic is inefficient. These problems can be solved by
employing an entity called a Resource Directory (RD), which hosts employing an entity called a Resource Directory (RD), which hosts
descriptions of resources held on other servers, allowing lookups to descriptions of resources held on other servers, allowing lookups to
be performed for those resources. This document specifies the web be performed for those resources. This document specifies the web
interfaces that a Resource Directory supports in order for web interfaces that a Resource Directory supports in order for web
skipping to change at page 1, line 43 skipping to change at page 1, line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 7, 2016. This Internet-Draft will expire on April 18, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 29 skipping to change at page 2, line 29
3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5
3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6
3.2. Use Case: Home and Building Automation . . . . . . . . . 7 3.2. Use Case: Home and Building Automation . . . . . . . . . 7
3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7 3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7
4. Simple Directory Discovery . . . . . . . . . . . . . . . . . 8 4. Simple Directory Discovery . . . . . . . . . . . . . . . . . 8
4.1. Finding a Directory Server . . . . . . . . . . . . . . . 9 4.1. Finding a Directory Server . . . . . . . . . . . . . . . 9
4.2. Third-party registration . . . . . . . . . . . . . . . . 10 4.2. Third-party registration . . . . . . . . . . . . . . . . 10
5. Resource Directory Function Set . . . . . . . . . . . . . . . 10 5. Resource Directory Function Set . . . . . . . . . . . . . . . 10
5.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 10 5.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2. Registration . . . . . . . . . . . . . . . . . . . . . . 12 5.2. Registration . . . . . . . . . . . . . . . . . . . . . . 12
5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4. Removal . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.5. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 17 5.5. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 17
6. Group Function Set . . . . . . . . . . . . . . . . . . . . . 18 5.6. Update Endpoint Links . . . . . . . . . . . . . . . . . . 19
6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 18 6. Group Function Set . . . . . . . . . . . . . . . . . . . . . 21
6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 20 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 22
7. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . 21 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 24
8. New Link-Format Attributes . . . . . . . . . . . . . . . . . 25 7. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . 25
8.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 25 8. New Link-Format Attributes . . . . . . . . . . . . . . . . . 29
8.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 25 8.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 29
9. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 26 8.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 30
9.1. DNS-based Service discovery . . . . . . . . . . . . . . . 26 9. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 30
9.2. mapping ins to <Instance> . . . . . . . . . . . . . . . . 27 9.1. DNS-based Service discovery . . . . . . . . . . . . . . . 30
9.3. Mapping rt to <ServiceType> . . . . . . . . . . . . . . . 28 9.2. mapping ins to <Instance> . . . . . . . . . . . . . . . . 31
9.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 28 9.3. Mapping rt to <ServiceType> . . . . . . . . . . . . . . . 32
9.5. TXT Record key=value strings . . . . . . . . . . . . . . 28 9.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 32
9.6. Importing resource links into DNS-SD . . . . . . . . . . 29 9.5. TXT Record key=value strings . . . . . . . . . . . . . . 32
10. Security Considerations . . . . . . . . . . . . . . . . . . . 30 9.6. Importing resource links into DNS-SD . . . . . . . . . . 33
10.1. Endpoint Identification and Authentication . . . . . . . 30 10. Security Considerations . . . . . . . . . . . . . . . . . . . 34
10.2. Access Control . . . . . . . . . . . . . . . . . . . . . 30 10.1. Endpoint Identification and Authentication . . . . . . . 34
10.3. Denial of Service Attacks . . . . . . . . . . . . . . . 30 10.2. Access Control . . . . . . . . . . . . . . . . . . . . . 34
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 10.3. Denial of Service Attacks . . . . . . . . . . . . . . . 34
11.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 31 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
11.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 31 11.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 35
11.3. RD Parameter Registry . . . . . . . . . . . . . . . . . 31 11.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 35
12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32 11.3. RD Parameter Registry . . . . . . . . . . . . . . . . . 35
12.1. Lighting Installation . . . . . . . . . . . . . . . . . 32 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 36
12.1.1. Installation Characteristics . . . . . . . . . . . . 32 12.1. Lighting Installation . . . . . . . . . . . . . . . . . 36
12.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 34 12.1.1. Installation Characteristics . . . . . . . . . . . . 36
12.1.3. DNS entries . . . . . . . . . . . . . . . . . . . . 37 12.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 38
12.1.4. RD Operation . . . . . . . . . . . . . . . . . . . . 40 12.1.3. DNS entries . . . . . . . . . . . . . . . . . . . . 41
12.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 40 12.1.4. RD Operation . . . . . . . . . . . . . . . . . . . . 44
12.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 41 12.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 44
12.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 42 12.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 45
12.2.3. Alternate Base URI . . . . . . . . . . . . . . . . . 43 12.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 46
12.2.4. LWM2M Update Endpoint Registration . . . . . . . . . 44 12.2.3. Alternate Base URI . . . . . . . . . . . . . . . . . 47
12.2.5. LWM2M De-Register Endpoint . . . . . . . . . . . . . 44 12.2.4. LWM2M Update Endpoint Registration . . . . . . . . . 48
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 12.2.5. LWM2M De-Register Endpoint . . . . . . . . . . . . . 48
14. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 44 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 14. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 48
15.1. Normative References . . . . . . . . . . . . . . . . . . 47 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 51
15.2. Informative References . . . . . . . . . . . . . . . . . 47 15.1. Normative References . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 15.2. Informative References . . . . . . . . . . . . . . . . . 52
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained the REST architecture in a suitable form for the most constrained
nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M)
applications such as smart energy and building automation. applications such as smart energy and building automation.
The discovery of resources offered by a constrained server is very The discovery of resources offered by a constrained server is very
skipping to change at page 11, line 10 skipping to change at page 11, line 10
request to "/.well-known/core" and including a Resource Type (rt) request to "/.well-known/core" and including a Resource Type (rt)
parameter [RFC6690] with the value "core.rd" in the query string. parameter [RFC6690] with the value "core.rd" in the query string.
Likewise, a Resource Type parameter value of "core.rd-lookup" is used Likewise, a Resource Type parameter value of "core.rd-lookup" is used
to discover the RD Lookup Function Set. Upon success, the response to discover the RD Lookup Function Set. Upon success, the response
will contain a payload with a link format entry for each RD will contain a payload with a link format entry for each RD
discovered, with the URL indicating the root resource of the RD. discovered, with the URL indicating the root resource of the RD.
When performing multicast discovery, the multicast IP address used When performing multicast discovery, the multicast IP address used
will depend on the scope required and the multicast capabilities of will depend on the scope required and the multicast capabilities of
the network. the network.
HTTP does not support multicast and consequently discovery has no
HTTP interface.
An RD implementation of this specification MUST support query An RD implementation of this specification MUST support query
filtering for the rt parameter as defined in [RFC6690]. filtering for the rt parameter as defined in [RFC6690].
The discovery request interface is specified as follows: The discovery request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: GET Method: GET
URI Template: /.well-known/core{?rt} URI Template: /.well-known/core{?rt}
skipping to change at page 11, line 34 skipping to change at page 11, line 37
"core.rd-lookup", "core.rd-group" or "core.rd*" "core.rd-lookup", "core.rd-group" or "core.rd*"
Content-Type: application/link-format (if any) Content-Type: application/link-format (if any)
Content-Type: application/link-format+json (if any) Content-Type: application/link-format+json (if any)
Content-Type: application/link-format+cbor (if any) Content-Type: application/link-format+cbor (if any)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.05 "Content" or 200 "OK" with an application/link-format, Success: 2.05 "Content" with an application/link-format,
application/link-format+json, or application/link-format+cbor application/link-format+json, or application/link-format+cbor
payload containing one or more matching entries for the RD payload containing one or more matching entries for the RD
resource. resource.
Failure: 4.04 "Not Found" or 404 "Not Found" is returned in case no Failure: 4.04 "Not Found" is returned in case no matching entry is
matching entry is found for a unicast request. found for a unicast request.
Failure: 4.00 "Bad Request" or 400 "Bad Request" is returned in case Failure: 4.00 "Bad Request" is returned in case of a malformed
of a malformed request for a unicast request. request for a unicast request.
Failure: No error response to a multicast request. Failure: No error response to a multicast request.
HTTP support : NO
The following example shows an endpoint discovering an RD using this The following example shows an endpoint discovering an RD using this
interface, thus learning that the base RD resource is, in this interface, thus learning that the base RD resource is, in this
example, at /rd. Note that it is up to the RD to choose its base RD example, at /rd. Note that it is up to the RD to choose its base RD
resource, although diagnostics and debugging is facilitated by using resource, although diagnostics and debugging is facilitated by using
the base paths specified here where possible. the base paths specified here where possible.
EP RD EP RD
| | | |
| ----- GET /.well-known/core?rt=core.rd* ------> | | ----- GET /.well-known/core?rt=core.rd* ------> |
| | | |
skipping to change at page 12, line 26 skipping to change at page 12, line 31
</rd>;rt="core.rd", </rd>;rt="core.rd",
</rd-lookup>;rt="core.rd-lookup", </rd-lookup>;rt="core.rd-lookup",
</rd-group>;rt="core.rd-group" </rd-group>;rt="core.rd-group"
5.2. Registration 5.2. Registration
After discovering the location of an RD Function Set, an endpoint MAY After discovering the location of an RD Function Set, an endpoint MAY
register its resources using the registration interface. This register its resources using the registration interface. This
interface accepts a POST from an endpoint containing the list of interface accepts a POST from an endpoint containing the list of
resources to be added to the directory as the message payload in the resources to be added to the directory as the message payload in the
CoRE Link Format [RFC6690], JSON CoRE Link Format CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link-
[I-D.ietf-core-links-json], or CBOR CoRE Link Format (application/ format+json), or CBOR CoRE Link Format (application/link-format+cbor)
link-format+cbor) along with query string parameters indicating the [I-D.ietf-core-links-json], along with query string parameters
name of the endpoint, its domain and the lifetime of the indicating the name of the endpoint, its domain and the lifetime of
registration. All parameters except the endpoint name are optional. the registration. All parameters except the endpoint name are
It is expected that other specifications will define further optional. It is expected that other specifications will define
parameters (see Section 11.3). The RD then creates a new resource or further parameters (see Section 11.3). The RD then creates a new
updates an existing resource in the RD and returns its location. An resource or updates an existing resource in the RD and returns its
endpoint MUST use that location when refreshing registrations using location. An endpoint MUST use that location when refreshing
this interface. Endpoint resources in the RD are kept active for the registrations using this interface. Endpoint resources in the RD are
period indicated by the lifetime parameter. The endpoint is kept active for the period indicated by the lifetime parameter. The
responsible for refreshing the entry within this period using either endpoint is responsible for refreshing the entry within this period
the registration or update interface. The registration interface using either the registration or update interface. The registration
MUST be implemented to be idempotent, so that registering twice with interface MUST be implemented to be idempotent, so that registering
the same endpoint parameter does not create multiple RD entries. twice with the same endpoint parameter does not create multiple RD
entries.
The registration request interface is specified as follows: The registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+rd}{?ep,d,et,lt,con} URI Template: /{+rd}{?ep,d,et,lt,con}
URI Template Variables: URI Template Variables:
skipping to change at page 14, line 11 skipping to change at page 14, line 19
resource returned in the Location is only for the purpose of the resource returned in the Location is only for the purpose of the
Update (POST) and Removal (DELETE), and MUST NOT implement GET or Update (POST) and Removal (DELETE), and MUST NOT implement GET or
PUT methods. PUT methods.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following example shows an endpoint with the name "node1" The following example shows an endpoint with the name "node1"
registering two resources to an RD using this interface. The registering two resources to an RD using this interface. The
resulting location /rd/4521 is just an example of an RD generated resulting location /rd/4521 is just an example of an RD generated
location. location.
EP RD EP RD
| | | |
| --- POST /rd?ep=node1 "</sensors..." -------> | | --- POST /rd?ep=node1 "</sensors..." -------> |
| | | |
| | | |
| <-- 2.01 Created Location: /rd/4521 ---------- | | <-- 2.01 Created Location: /rd/4521 ---------- |
| | | |
Req: POST coap://rd.example.com/rd?ep=node1 Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4521 Location: /rd/4521
Req: POST /rd?ep=node1 HTTP/1.1
Host : example.com
Content-Type: application/link-format
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor"
Res: 201 Created
Location: /rd/4521
5.3. Update 5.3. Update
The update interface is used by an endpoint to refresh or update its The update interface is used by an endpoint to refresh or update its
registration with an RD. To use the interface, the endpoint sends a registration with an RD. To use the interface, the endpoint sends a
POST request to the resource returned in the Location option in the POST request to the resource returned in the Location option in the
response to the first registration. An update MAY update the response to the first registration. An update MAY update the
lifetime or context parameters if they have changed since the last lifetime or context parameters if they have changed since the last
registration or update. Parameters that have not changed SHOULD NOT registration or update. Parameters that have not changed SHOULD NOT
be included in an update. Upon receiving an update request, the RD be included in an update. Upon receiving an update request, the RD
resets the timeout for that endpoint and updates the scheme, IP resets the timeout for that endpoint and updates the scheme, IP
address and port of the endpoint (using the source address of the address and port of the endpoint (using the source address of the
update, or the context parameter if present). update, or the context parameter if present).
An update MAY optionally add or replace links for the endpoint by An update MAY optionally add or replace links for the endpoint by
including those links in the payload of the update as a CoRE Link including those links in the payload of the update as a CoRE Link
Format document. Including links in an update message greatly Format document. Including links in an update message greatly
increases the load on an RD and SHOULD be done infrequently. A link increases the load on an RD and SHOULD be done infrequently. A link
is replaced only if both the target URI and relation type match (see is replaced only if both the target URI and relation type match (see
Section 10.1). Section 10.1)
The update request interface is specified as follows: The update request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+location}{?lt,con} URI Template: /{+location}{?lt,con}
URI Template Variables: URI Template Variables:
skipping to change at page 15, line 31 skipping to change at page 16, line 4
address and port at which this server is available in the form address and port at which this server is available in the form
scheme://host:port. Optional. In the absence of this scheme://host:port. Optional. In the absence of this
parameter the scheme of the protocol, source IP address and parameter the scheme of the protocol, source IP address and
source port used to register are assumed. This parameter is source port used to register are assumed. This parameter is
compulsory when the directory is filled by a third party such compulsory when the directory is filled by a third party such
as an installation tool. as an installation tool.
Content-Type: application/link-format (optional) Content-Type: application/link-format (optional)
Content-Type: application/link-format+json (optional) Content-Type: application/link-format+json (optional)
Content-Type: application/link-format+cbor (optional) Content-Type: application/link-format+cbor (optional)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.04 "Changed" 0r 204 "No Content" in the update was Success: 2.04 "Changed" or 204 "No Content" in the update was
successfully processed. successfully processed.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following example shows an endpoint updating its registration at The following example shows an endpoint updating its registration at
an RD using this interface. an RD using this interface.
EP RD EP RD
| | | |
| --- POST /rd/4521 --------------------------> | | --- POST /rd/4521 --------------------------> |
| | | |
| | | |
| <-- 2.04 Changed ---------------------------- | | <-- 2.04 Changed ---------------------------- |
| | | |
skipping to change at page 16, line 51 skipping to change at page 17, line 22
Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following examples shows successful removal of the endpoint from The following examples shows successful removal of the endpoint from
the RD. the RD.
EP RD EP RD
| | | |
| --- DELETE /rd/4521 ------------------------> | | --- DELETE /rd/4521 ------------------------> |
| | | |
| | | |
| <-- 2.02 Deleted ---------------------------- | | <-- 2.02 Deleted ---------------------------- |
| | | |
skipping to change at page 17, line 23 skipping to change at page 17, line 45
Req: DELETE /rd/4521 Req: DELETE /rd/4521
Res: 2.02 Deleted Res: 2.02 Deleted
5.5. Read Endpoint Links 5.5. Read Endpoint Links
Some endpoints may wish to manage their links as a collection, and Some endpoints may wish to manage their links as a collection, and
may need to read the current set of links in order to determine link may need to read the current set of links in order to determine link
maintenance operations. maintenance operations.
One or more links MAY be selected by using query filtering as
specified in [RFC6690] Section 4.1
The read request interface is specified as follows: The read request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: GET Method: GET
URI Template: /{+location}{?rt,if,ct} URI Template: /{+location}{?href,rel,rt,if,ct}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location path returned by the RD as a
result of a successful earlier registration. result of a successful earlier registration.
href,rel,rt,if,ct := link relations and attributes specified in
the query in order to select particular links based on their
relations and attributes. "href" denotes the URI target of the
link. See [RFC6690] Sec. 4.1
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
Success: 2.05 "Content" or 200 "OK" upon success with an Success: 2.05 "Content" or 200 "OK" upon success with an
"application/link-format", "application/link-format+cbor", or "application/link-format", "application/link-format+cbor", or
"application/link-format+json" payload. "application/link-format+json" payload.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following examples show successful read of the endpoint links The following examples show successful read of the endpoint links
from the RD. from the RD.
EP RD EP RD
| | | |
| --- GET /rd/4521 ------------------------> | | --- GET /rd/4521 ------------------------> |
| | | |
| | | |
| <-- 2.05 Content </sensors... ---------------- | | <-- 2.05 Content </sensors... ---------------- |
| | | |
Req: GET /rd/4521 Req: GET /rd/4521
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
5.6. Update Endpoint Links
A PATCH update adds, removes or changes links for the endpoint by
including link update information in the payload of the update as a
merge-patch+json format [RFC7396] document.
One or more links are selected for update by using query filtering as
specified in [RFC6690] Section 4.1
The query filter selects the links to be modified or deleted, by
matching the query parameter values to the values of the link
attributes.
When the query parameters are not present in the request, the payload
specifies links to be added to the target document. When the query
parameters are present, the attribute names and values in the query
parameters select one or more links on which to apply the PATCH
operation.
If an attribute name specified in the PATCH document exists in any
the set of selected links, all occurrences of the attribute value in
the target document MUST be updated using the value from the PATCH
payload. If the attribute name is not present in any selected links,
the attribute MUST be added to the links.
The update request interface is specified as follows:
Interaction: EP -> RD
Method: PATCH
URI Template: /{+location}{?href,rel,rt,if,ct}
URI Template Variables:
location := This is the Location path returned by the RD as a
result of a successful earlier registration.
href,rel,rt,if,ct := link relations and attributes specified in
the query in order to select particular links based on their
relations and attributes. "href" denotes the URI target of the
link. See [RFC6690] Sec. 4.1
Content-Format: application/merge-patch+json (mandatory)
The following response codes are defined for this interface:
Success: 2.04 "Changed" 0r 204 "No Content" in the update was
successfully processed.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource
does not exist (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation.
HTTP support: YES
The following examples show an endpoint adding </sensors/humid>,
modifying </sensors/temp>, and removing </sensors/light> links in RD
using the Update Endpoint Links function.
The following example shows an EP adding the link </sensors/
humid>;ct=41;rt="humidity-s";if="sensor" to the collection of links
at the location /rd/4521.
EP RD
| |
| --- PATCH /rd/4521---------------------------> |
| |
| |
| <-- 2.04 Changed ---------------------------- |
| |
Req: PATCH /rd/4521
Payload:
[{"href":"/sensors/humid","ct": 41, "rt": "humidity-s", "if": "sensor"}]
Content-Format:
application/merge-patch+json
Res: 2.04 Changed
The following example shows an EP modifying all links at the location
/rd/4521 which are identified by href="/sensors/temp", from the
initial link-value of </sensors/temp>;rt="temperature" to the new
link-value </sensors/temp>;rt="temperature-c";if="sensor" by changing
the value of the link attribute "rt" and adding the link attribute
if="sensor" using the PATCH operation with the supplied merge-
patch+json document payload.
EP RD
| |
| --- PATCH /rd/4521?href="/sensors/temp" ----> |
| |
| |
| <-- 2.04 Changed ---------------------------- |
| |
Req: PATCH /rd/4521?href="/sensors/temp"
Payload:
{"rt": "temperature-c", "if": "sensor"},
Content-Format:
application/merge-patch+json
Res: 2.04 Changed
This example shows an EP removing all links at the location /rd/4521
which are identified by href="/sensors/light".
EP RD
| |
| --- PATCH /rd/4521?href="/sensors/light" ----> |
| |
| |
| <-- 2.04 Changed ---------------------------- |
| |
Req: PATCH /rd/4521?href="/sensors/light"
Payload:
{null}
Content-Format:
application/merge-patch+json
Res: 2.04 Changed
6. Group Function Set 6. Group Function Set
This section defines a function set for the creation of groups of This section defines a function set for the creation of groups of
endpoints for the purpose of managing and looking up endpoints for endpoints for the purpose of managing and looking up endpoints for
group operations. The group function set is similar to the resource group operations. The group function set is similar to the resource
directory function set, in that a group may be created or removed. directory function set, in that a group may be created or removed.
However unlike an endpoint entry, a group entry consists of a list of However unlike an endpoint entry, a group entry consists of a list of
endpoints and does not have a lifetime associated with it. In order endpoints and does not have a lifetime associated with it. In order
to make use of multicast requests with CoAP, a group MAY have a to make use of multicast requests with CoAP, a group MAY have a
multicast address associated with it. multicast address associated with it.
skipping to change at page 19, line 48 skipping to change at page 23, line 26
be included with the new group entry. This Location MUST be a be included with the new group entry. This Location MUST be a
stable identifier generated by the RD as it is used for delete stable identifier generated by the RD as it is used for delete
operations on this registration. operations on this registration.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following example shows an EP registering a group with the name The following example shows an EP registering a group with the name
"lights" which has two endpoints to an RD using this interface. The "lights" which has two endpoints to an RD using this interface. The
resulting location /rd-group/12 is just an example of an RD generated resulting location /rd-group/12 is just an example of an RD generated
group location. group location.
EP RD EP RD
| | | |
| - POST /rd-group?gp=lights "<>;ep=node1..." --> | | - POST /rd-group?gp=lights "<>;ep=node1..." --> |
| | | |
| | | |
| <---- 2.01 Created Location: /rd-group/12 ---- | | <---- 2.01 Created Location: /rd-group/12 ---- |
| | | |
Req: POST coap://rd.example.com/rd-group?gp=lights Req: POST coap://rd.example.com/rd-group?gp=lights
Payload: Payload:
<>;ep="node1", <>;ep="node1",
<>;ep="node2" <>;ep="node2"
Res: 2.01 Created Res: 2.01 Created
Location: /rd-group/12 Location: /rd-group/12
Req: POST /rd-group?gp=lights HTTP/1.1
Host: example.com
Accept: application/link-format
Payload:
<>;ep="node1",
<>;ep="node2"
Res: 201 Created
Location: /rd-group/12
6.2. Group Removal 6.2. Group Removal
A group can be removed simply by sending a removal message to the A group can be removed simply by sending a removal message to the
location returned when registering the group. Removing a group MUST location returned when registering the group. Removing a group MUST
NOT remove the endpoints of the group from the RD. NOT remove the endpoints of the group from the RD.
The removal request interface is specified as follows: The removal request interface is specified as follows:
Interaction: Manager -> RD Interaction: Manager -> RD
skipping to change at page 21, line 5 skipping to change at page 24, line 45
Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES
The following examples shows successful removal of the group from the The following examples shows successful removal of the group from the
RD. RD.
EP RD EP RD
| | | |
| --- DELETE /rd-group/412 -------------------> | | --- DELETE /rd-group/412 -------------------> |
| | | |
| | | |
| <-- 2.02 Deleted ---------------------------- | | <-- 2.02 Deleted ---------------------------- |
| | | |
skipping to change at page 23, line 8 skipping to change at page 27, line 8
entry is found for a unicast request. entry is found for a unicast request.
Failure: No error response to a multicast request. Failure: No error response to a multicast request.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
The examples in this section assume a host with IP address FDFD::123 HTTP support: YES
and a default CoAP port 61616. The following example shows a client
performing a resource lookup: The examples in this section assume a CoAP host with IP address
FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and
do not change the nature of the examples. The following example
shows a client performing a resource lookup:
Client RD Client RD
| | | |
| ----- GET /rd-lookup/res?rt=temperature -----------------> | | ----- GET /rd-lookup/res?rt=temperature -----------------> |
| | | |
| | | |
| <-- 2.05 Content <coap://[FDFD::123]:61616/temp>;--------- | | <-- 2.05 Content <coap://[FDFD::123]:61616/temp>;--------- |
| rt="temperature" -------- | | rt="temperature" -------- |
| | | |
skipping to change at page 32, line 39 skipping to change at page 36, line 39
The IANA policy for future additions to the sub-registry is "Expert The IANA policy for future additions to the sub-registry is "Expert
Review" as described in [RFC5226]. Review" as described in [RFC5226].
12. Examples 12. Examples
Examples are added here. Examples are added here.
12.1. Lighting Installation 12.1. Lighting Installation
This example shows a simplified lighting installation which makes use This example shows a simplified lighting installation which makes use
of the Resource Directory (RD) to facilitate the installation and of the Resource Directory (RD) with a CoAP interface to facilitate
start up of the application code in the lights and sensors. In the installation and start up of the application code in the lights
particular, the example leads to the definition of a group and the and sensors. In particular, the example leads to the definition of a
enabling of the corresponding multicast address. No conclusions must group and the enabling of the corresponding multicast address. No
be drawn on the realization of actual installation procedures, conclusions must be drawn on the realization of actual installation
because the example "emphasizes" some of the issues that may procedures, because the example "emphasizes" some of the issues that
influence the use of the RD. may influence the use of the RD.
12.1.1. Installation Characteristics 12.1.1. Installation Characteristics
The example assumes that the installation is managed. That means The example assumes that the installation is managed. That means
that a Commissioning Tool (CT) is used to authorize the addition of that a Commissioning Tool (CT) is used to authorize the addition of
nodes, name them, and name their services. The CT can be connected nodes, name them, and name their services. The CT can be connected
to the installation in many ways: the CT can be part of the to the installation in many ways: the CT can be part of the
installation network, connected by WiFi to the installation network, installation network, connected by WiFi to the installation network,
or connected via GPRS link, or other method. or connected via GPRS link, or other method.
skipping to change at page 44, line 36 skipping to change at page 48, line 36
Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Brandt, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Brandt,
Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have provided Matthieu Vial, Mohit Sethi, Sampo Ukkola and Linyi Tian have provided
helpful comments, discussions and ideas to improve and shape this helpful comments, discussions and ideas to improve and shape this
document. Zach would also like to thank his colleagues from the EU document. Zach would also like to thank his colleagues from the EU
FP7 SENSEI project, where many of the resource directory concepts FP7 SENSEI project, where many of the resource directory concepts
were originally developed. were originally developed.
14. Changelog 14. Changelog
changes from -04 to -05
o added Update Endpoint Links using PATCH
o http access made explicit in interface specification
o Added http examples
Changes from -03 to -04: Changes from -03 to -04:
o Added http response codes o Added http response codes
o Clarified endpoint name usage o Clarified endpoint name usage
o Add application/link-format+cbor content-format o Add application/link-format+cbor content-format
Changes from -02 to -03: Changes from -02 to -03:
skipping to change at page 47, line 10 skipping to change at page 51, line 17
during updates. during updates.
o Changed the lookup interface to accept endpoint and Domain as o Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup. query string parameters to control the scope of a lookup.
15. References 15. References
15.1. Normative References 15.1. Normative References
[I-D.ietf-core-links-json] [I-D.ietf-core-links-json]
Bormann, C., "Representing CoRE Link Collections in JSON", Li, K., Rahman, A., and C. Bormann, "Representing CoRE
draft-ietf-core-links-json-02 (work in progress), July Formats in JSON and CBOR", draft-ietf-core-links-json-03
2014. (work in progress), July 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66,
3986, January 2005. RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
Cheshire, "Internet Assigned Numbers Authority (IANA) Cheshire, "Internet Assigned Numbers Authority (IANA)
Procedures for the Management of the Service Name and Procedures for the Management of the Service Name and
Transport Protocol Port Number Registry", BCP 165, RFC Transport Protocol Port Number Registry", BCP 165,
6335, August 2011. RFC 6335, DOI 10.17487/RFC6335, August 2011,
<http://www.rfc-editor.org/info/rfc6335>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012. and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<http://www.rfc-editor.org/info/rfc6570>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>.
[RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", RFC 6763, February 2013. Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013,
<http://www.rfc-editor.org/info/rfc6763>.
[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
DOI 10.17487/RFC7396, October 2014,
<http://www.rfc-editor.org/info/rfc7396>.
15.2. Informative References 15.2. Informative References
[I-D.ietf-core-interfaces] [I-D.ietf-core-interfaces]
Shelby, Z. and M. Vial, "CoRE Interfaces", draft-ietf- Shelby, Z., Vial, M., and M. Koster, "CoRE Interfaces",
core-interfaces-02 (work in progress), November 2014. draft-ietf-core-interfaces-03 (work in progress), July
2015.
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities", [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, November 1987. STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
<http://www.rfc-editor.org/info/rfc1034>.
[RFC1123] Braden, R., "Requirements for Internet Hosts - Application [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts -
and Support", STD 3, RFC 1123, October 1989. Application and Support", STD 3, RFC 1123,
DOI 10.17487/RFC1123, October 1989,
<http://www.rfc-editor.org/info/rfc1123>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, March 2008. Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
<http://www.rfc-editor.org/info/rfc5198>.
[RFC6775] Shelby, Z., Chakrabarti, S., Nordmark, E., and C. Bormann, [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C.
"Neighbor Discovery Optimization for IPv6 over Low-Power Bormann, "Neighbor Discovery Optimization for IPv6 over
Wireless Personal Area Networks (6LoWPANs)", RFC 6775, Low-Power Wireless Personal Area Networks (6LoWPANs)",
November 2012. RFC 6775, DOI 10.17487/RFC6775, November 2012,
<http://www.rfc-editor.org/info/rfc6775>.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June Protocol (HTTP/1.1): Message Syntax and Routing",
2014. RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, June 2014. Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7390] Rahman, A. and E. Dijk, "Group Communication for the [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
Constrained Application Protocol (CoAP)", RFC 7390, the Constrained Application Protocol (CoAP)", RFC 7390,
October 2014. DOI 10.17487/RFC7390, October 2014,
<http://www.rfc-editor.org/info/rfc7390>.
Editorial Comments Editorial Comments
[_TEMPLATE_TODO] This text needs some help from an RFC 6570 expert. [_TEMPLATE_TODO] This text needs some help from an RFC 6570 expert.
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
ARM ARM
150 Rose Orchard 150 Rose Orchard
 End of changes. 50 change blocks. 
111 lines changed or deleted 326 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/