CoRE Resource Directory
draft-ietf-core-resource-directory-14
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 9176.
|
|
|---|---|---|---|
| Authors | Zach Shelby , Michael Koster , Carsten Bormann , Peter Van der Stok , Christian Amsüss | ||
| Last updated | 2018-07-02 | ||
| Replaces | draft-shelby-core-resource-directory | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews |
GENART Telechat review
(of
-25)
by Russ Housley
Almost ready
|
||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | Jaime Jimenez | ||
| IESG | IESG state | Became RFC 9176 (Proposed Standard) | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | Alexey Melnikov | ||
| Send notices to | "Jaime Jimenez" <jaime.jimenez@ericsson.com> |
draft-ietf-core-resource-directory-14
quot;base URI", "base path"
o moved simple registration to registration section
changes from -08 to -09
o clarified the "example use" of the base RD resource values /rd,
/rd-lookup, and /rd-group.
o changed "ins" ABNF notation.
o various editorial improvements, including in examples
o clarifications for RDAO
changes from -07 to -08
o removed link target value returned from domain and group lookup
types
o Maximum length of domain parameter 63 bytes for consistency with
group
o removed option for simple POST of link data, don't require a
.well-known/core resource to accept POST data and handle it in a
special way; we already have /rd for that
o add IPv6 ND Option for discovery of an RD
o clarify group configuration section 6.1 that endpoints must be
registered before including them in a group
o removed all superfluous client-server diagrams
o simplified lighting example
o introduced Commissioning Tool
Shelby, et al. Expires January 3, 2019 [Page 59]
Internet-Draft CoRE Resource Directory July 2018
o RD-Look-up text is extended.
changes from -06 to -07
o added text in the discovery section to allow content format hints
to be exposed in the discovery link attributes
o editorial updates to section 9
o update author information
o minor text corrections
Changes from -05 to -06
o added note that the PATCH section is contingent on the progress of
the PATCH method
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:
o Added http response codes
o Clarified endpoint name usage
o Add application/link-format+cbor content-format
Changes from -02 to -03:
o Added an example for lighting and DNS integration
o Added an example for RD use in OMA LWM2M
o Added Read Links operation for link inspection by endpoints
o Expanded DNS-SD section
o Added draft authors Peter van der Stok and Michael Koster
Changes from -01 to -02:
Shelby, et al. Expires January 3, 2019 [Page 60]
Internet-Draft CoRE Resource Directory July 2018
o Added a catalogue use case.
o Changed the registration update to a POST with optional link
format payload. Removed the endpoint type update from the update.
o Additional examples section added for more complex use cases.
o New DNS-SD mapping section.
o Added text on endpoint identification and authentication.
o Error code 4.04 added to Registration Update and Delete requests.
o Made 63 bytes a SHOULD rather than a MUST for endpoint name and
resource type parameters.
Changes from -00 to -01:
o Removed the ETag validation feature.
o Place holder for the DNS-SD mapping section.
o Explicitly disabled GET or POST on returned Location.
o New registry for RD parameters.
o Added support for the JSON Link Format.
o Added reference to the Groupcomm WG draft.
Changes from -05 to WG Document -00:
o Updated the version and date.
Changes from -04 to -05:
o Restricted Update to parameter updates.
o Added pagination support for the Lookup interface.
o Minor editing, bug fixes and reference updates.
o Added group support.
o Changed rt to et for the registration and update interface.
Changes from -03 to -04:
Shelby, et al. Expires January 3, 2019 [Page 61]
Internet-Draft CoRE Resource Directory July 2018
o Added the ins= parameter back for the DNS-SD mapping.
o Integrated the Simple Directory Discovery from Carsten.
o Editorial improvements.
o Fixed the use of ETags.
o Fixed tickets 383 and 372
Changes from -02 to -03:
o Changed the endpoint name back to a single registration parameter
ep= and removed the h= and ins= parameters.
o Updated REST interface descriptions to use RFC6570 URI Template
format.
o Introduced an improved RD Lookup design as its own function set.
o Improved the security considerations section.
o Made the POST registration interface idempotent by requiring the
ep= parameter to be present.
Changes from -01 to -02:
o Added a terminology section.
o Changed the inclusion of an ETag in registration or update to a
MAY.
o Added the concept of an RD Domain and a registration parameter for
it.
o Recommended the Location returned from a registration to be
stable, allowing for endpoint and Domain information to be changed
during updates.
o Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup.
14. References
Shelby, et al. Expires January 3, 2019 [Page 62]
Internet-Draft CoRE Resource Directory July 2018
14.1. Normative References
[I-D.ietf-core-links-json]
Li, K., Rahman, A., and C. Bormann, "Representing
Constrained RESTful Environments (CoRE) Link Format in
JSON and CBOR", draft-ietf-core-links-json-10 (work in
progress), February 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<https://www.rfc-editor.org/info/rfc5988>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/info/rfc6570>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>.
[RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013,
<https://www.rfc-editor.org/info/rfc6763>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
14.2. Informative References
[ER] Chen, P., "The entity-relationship model---toward a
unified view of data", ACM Transactions on Database
Systems Vol. 1, pp. 9-36, DOI 10.1145/320434.320440, March
1976.
Shelby, et al. Expires January 3, 2019 [Page 63]
Internet-Draft CoRE Resource Directory July 2018
[I-D.arkko-core-dev-urn]
Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource
Names for Device Identifiers", draft-arkko-core-dev-urn-05
(work in progress), October 2017.
[I-D.bormann-t2trg-rel-impl]
Bormann, C., "impl-info: A link relation type for
disclosing implementation information", draft-bormann-
t2trg-rel-impl-00 (work in progress), January 2018.
[I-D.ietf-ace-oauth-authz]
Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and
H. Tschofenig, "Authentication and Authorization for
Constrained Environments (ACE) using the OAuth 2.0
Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-12
(work in progress), May 2018.
[I-D.ietf-anima-bootstrapping-keyinfra]
Pritikin, M., Richardson, M., Behringer, M., Bjarnason,
S., and K. Watsen, "Bootstrapping Remote Secure Key
Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping-
keyinfra-16 (work in progress), June 2018.
[I-D.silverajan-core-coap-protocol-negotiation]
Silverajan, B. and M. Ocak, "CoAP Protocol Negotiation",
draft-silverajan-core-coap-protocol-negotiation-08 (work
in progress), March 2018.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616,
DOI 10.17487/RFC2616, June 1999,
<https://www.rfc-editor.org/info/rfc2616>.
[RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C.
Bormann, "Neighbor Discovery Optimization for IPv6 over
Low-Power Wireless Personal Area Networks (6LoWPANs)",
RFC 6775, DOI 10.17487/RFC6775, November 2012,
<https://www.rfc-editor.org/info/rfc6775>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>.
Shelby, et al. Expires January 3, 2019 [Page 64]
Internet-Draft CoRE Resource Directory July 2018
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014,
<https://www.rfc-editor.org/info/rfc7390>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<https://www.rfc-editor.org/info/rfc7641>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>.
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
May 2018, <https://www.rfc-editor.org/info/rfc8392>.
Appendix A. Registration Management
This section describes how the registering endpoint can maintain the
registries that it created. The registering endpoint can be the
registree-ep or the CT. An endpoint SHOULD NOT use this interface
for registries that it did not create. The registries are resources
of the RD.
After the initial registration, the registering endpoint retains the
returned location of the Registration Resource for further
operations, including refreshing the registration in order to extend
the lifetime and "keep-alive" the registration. When the lifetime of
the registration has expired, the RD SHOULD NOT respond to discovery
queries concerning this endpoint. The RD SHOULD continue to provide
access to the Registration Resource after a registration time-out
occurs in order to enable the registering endpoint to eventually
refresh the registration. The RD MAY eventually remove the
registration resource for the purpose of garbage collection and
remove it from any group it belongs to. If the Registration Resource
is removed, the corresponding endpoint will need to be re-registered.
Shelby, et al. Expires January 3, 2019 [Page 65]
Internet-Draft CoRE Resource Directory July 2018
The Registration Resource may also be used to inspect the
registration resource using GET, update the registration, cancel the
registration using DELETE, do an endpoint lookup, or a group lookup.
These operations are described below.
A.1. Registration Update
The update interface is used by the registering endpoint to refresh
or update its registration with an RD. To use the interface, the
registering endpoint sends a POST request to the registration
resource returned by the initial registration operation.
An update MAY update the lifetime- or the context- registration
parameters "lt", "base" as in Section 5.3. Parameters that are not
being changed SHOULD NOT be included in an update. Adding parameters
that have not changed increases the size of the message but does not
have any other implications. Parameters MUST be included as query
parameters in an update operation as in Section 5.3.
A registration update resets the timeout of the registration to the
(possibly updated) lifetime of the registration, independent of
whether a "lt" parameter was given.
If the context of the registration is changed in an update explicitly
or implicitly, relative references submitted in the original
registration or later updates are resolved anew against the new
context (like in the original registration).
The registration update operation only describes the use of POST with
an empty payload. Future standards might describe the semantics of
using content formats and payloads with the POST method to update the
links of a registration (see Appendix A.4).
The update registration request interface is specified as follows:
Interaction: EP -> RD
Method: POST
URI Template: {+location}{?lt,con,extra-attrs*}
URI Template Variables:
location := This is the Location returned by the RD as a result
of a successful earlier registration.
Shelby, et al. Expires January 3, 2019 [Page 66]
Internet-Draft CoRE Resource Directory July 2018
lt := Lifetime (optional). Lifetime of the registration in
seconds. Range of 60-4294967295. If no lifetime is included,
the previous last lifetime set on a previous update or the
original registration (falling back to 90000) SHOULD be used.
base := Base URI (optional). This parameter updates the context
established in the original registration to a new value. If
the parameter is set in an update, it is stored by the RD as
the new Base URI under which to interpret the links of the
registration, following the same restrictions as in the
registration. If the parameter is not set and was set
explicitly before, the previous Base URI value is kept
unmodified. If the parameter is not set and was not set
explicitly before either, the source address and source port of
the update request are stored as the Base URI.
extra-attrs := Additional registration attributes (optional). As
with the registration, the RD processes them if it knows their
semantics. Otherwise, unknown attributes are stored as
endpoint attributes, overriding any previously stored endpoint
attributes of the same key.
Content-Format: none (no payload)
The following response codes are defined for this interface:
Success: 2.04 "Changed" or 204 "No Content" if 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 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
If the registration update fails with a "Service Unavailable"
response and a Max-Age option or Retry-After header, the registering
endpoint SHOULD retry the operation after the time indicated. If the
registration fails in another way, including request timeouts, or if
the time indicated excedes the remaining lifetime, the registering
endpoint SHOULD attempt registration again.
Shelby, et al. Expires January 3, 2019 [Page 67]
Internet-Draft CoRE Resource Directory July 2018
The following example shows the registering endpoint updates its
registration resource at an RD using this interface with the example
location value: /rd/4521.
Req: POST /rd/4521
Res: 2.04 Changed
The following example shows the registering endpoint updating its
registration resource at an RD using this interface with the example
location value: /rd/4521. The initial registration by the
registering endpoint set the following values:
o endpoint name (ep)=endpoint1
o lifetime (lt)=500
o context (con)=coap://local-proxy-old.example.com:5683
o payload of Figure 7
The initial state of the Resource Directory is reflected in the
following request:
Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content
Payload:
<coap://local-proxy-old.example.com:5683/sensors/temp>;ct=41;
rt="temperature"; anchor="coap://spurious.example.com:5683",
<coap://local-proxy-old.example.com:5683/sensors/light>;ct=41;
rt="light-lux"; if="sensor";
anchor="coap://local-proxy-old.example.com:5683"
The following example shows the registering endpoint changing the
context to "coaps://new.example.com:5684":
Req: POST /rd/4521?con=coaps://new.example.com:5684
Res: 2.04 Changed
The consecutive query returns:
Shelby, et al. Expires January 3, 2019 [Page 68]
Internet-Draft CoRE Resource Directory July 2018
Req: GET /rd-lookup/res?ep=endpoint1
Res: 2.01 Content
Payload:
<coaps://new.example.com:5684/sensors/temp>;ct=41;rt="temperature";
anchor="coap://spurious.example.com:5683",
<coaps://new.example.com:5684/sensors/light>;ct=41;rt="light-lux";
if="sensor"; anchor="coaps://new.example.com:5684",
A.2. Registration Removal
Although RD entries have soft state and will eventually timeout after
their lifetime, the registering endpoint SHOULD explicitly remove an
entry from the RD if it knows it will no longer be available (for
example on shut-down). This is accomplished using a removal
interface on the RD by performing a DELETE on the endpoint resource.
Removed registrations are implicitly removed from the groups to which
they belong.
The removal request interface is specified as follows:
Interaction: EP -> RD
Method: DELETE
URI Template: {+location}
URI Template Variables:
location := This is the Location returned by the RD as a result
of a successful earlier registration.
The following response codes are defined for this interface:
Success: 2.02 "Deleted" or 204 "No Content" upon successful deletion
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration 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
Shelby, et al. Expires January 3, 2019 [Page 69]
Internet-Draft CoRE Resource Directory July 2018
The following examples shows successful removal of the endpoint from
the RD with example location value /rd/4521.
Req: DELETE /rd/4521
Res: 2.02 Deleted
A.3. Read Endpoint Links
Some registering endpoints may wish to manage their links as a
collection, and may need to read the current set of links stored in
the registration resource, in order to determine link maintenance
operations.
One or more links MAY be selected by using query filtering as
specified in [RFC6690] Section 4.1
If no links are selected, the Resource Directory SHOULD return an
empty payload.
The read request interface is specified as follows:
Interaction: EP -> RD
Method: GET
URI Template: {+location}{?href,rel,rt,if,ct}
URI Template Variables:
location := This is the Location 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
The following response codes are defined for this interface:
Success: 2.05 "Content" or 200 "OK" upon success with an
"application/link-format", "application/link-format+cbor", or
"application/link-format+json" payload.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request.
Shelby, et al. Expires January 3, 2019 [Page 70]
Internet-Draft CoRE Resource Directory July 2018
Failure: 4.04 "Not Found" or 404 "Not Found". Registration 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 successful read of the endpoint links
from the RD, with example location value /rd/4521 and example
registration payload of Figure 7.
Req: GET /rd/4521
Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor";
anchor="coap://spurious.example.com:5683",
</sensors/light>;ct=41;rt="light-lux";if="sensor"
A.4. Update Endpoint Links
An iPATCH (or PATCH) update ([RFC8132]) can add, remove or change the
links of a registration.
Those operations are out of scope of this document, and will require
media types suitable for modifying sets of links.
A.5. Endpoint and group lookup
Endpoint and group lookups result in links to registration resources
and group resources, respectively. Endpoint registration resources
are annotated with their endpoint names (ep), sectors (d, if present)
and registration base URI (base) as well as a constant resource type
(rt="core.rd-ep"); the lifetime (lt) is not reported. Additional
endpoint attributes are added as link attributes to their endpoint
link unless their specification says otherwise.
Group resources are annotated with their group names (gp), sector (d,
if present) and multicast address (base, if present) as well as a
constant resource type (rt="core.rd-gp").
Serializations derived from Link Format, SHOULD present links to
groups and endpoints in path-absolute form or, if required, as
absolute references. (This approach avoids the RFC6690 ambiguities.)
Shelby, et al. Expires January 3, 2019 [Page 71]
Internet-Draft CoRE Resource Directory July 2018
While Endpoint Lookup does expose the registration resources, the RD
does not need to make them accessible to clients. Clients SHOULD NOT
attempt to dereference or manipulate them.
A Resource Directory can report endpoints or groups in lookup that
are not hosted at the same address. Lookup clients MUST be prepared
to see arbitrary URIs as registration or group resources in the
results and treat them as opaque identifiers; the precise semantics
of such links are left to future specifications.
For groups, a Resource Directory as specified here does not provide a
lookup mechanism for the resources that can be accessed on a group's
multicast address (ie. no lookup will return links like
"<coap://[ff35:30:2001:db8::1]/light>;..." for a group registered
with "base=coap://[ff35...]"). Such an additional lookup interface
could be specified in an extension document.
The following example shows a client performing an endpoint type (et)
lookup with the value oic.d.sensor (which is currently a registered
rt value):
Req: GET /rd-lookup/ep?et=oic.d.sensor
Res: 2.05 Content
</rd/1234>;base="coap://[2001:db8:3::127]:61616";ep="node5";
et="oic.d.sensor";ct="40",
</rd/4521>;base="coap://[2001:db8:3::129]:61616";ep="node7";
et="oic.d.sensor";ct="40";d="floor-3"
The following example shows a client performing a group lookup for
all groups:
Req: GET /rd-lookup/gp
Res: 2.05 Content
</rd-group/1>;gp="lights1";d="example.com";
base="coap://[ff35:30:2001:db8::1]",
</rd-group/2>;gp="lights2";d="example.com";
base="coap://[ff35:30:2001:db8::2]"
The following example shows a client performing a lookup for all
groups the endpoint "node1" belongs to:
Req: GET /rd-lookup/gp?ep=node1
Res: 2.05 Content
</rd-group/1>;gp="lights1"
Shelby, et al. Expires January 3, 2019 [Page 72]
Internet-Draft CoRE Resource Directory July 2018
Appendix B. Web links and the Resource Directory
Understanding the semantics of a link-format document and its URI
references is a journey through different documents ([RFC3986]
defining URIs, [RFC6690] defining link-format documents based on
[RFC8288] which defines link headers, and [RFC7252] providing the
transport). This appendix summarizes the mechanisms and semantics at
play from an entry in ".well-known/core" to a resource lookup.
This text is primarily aimed at people entering the field of
Constrained Restful Environments from applications that previously
did not use web mechanisms.
B.1. A simple example
Let's start this example with a very simple host, "2001:db8:f0::1".
A client that follows classical CoAP Discovery ([RFC7252] Section 7),
sends the following multicast request to learn about neighbours
supporting resources with resource-type "temperature".
The client sends a link-local multicast:
GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature
RES 2.05 Content
</temp>;rt=temperature;ct=0
where the response is sent by the server, "[2001:db8:f0::1]:5683".
While the client - on the practical or implementation side - can just
go ahead and create a new request to "[2001:db8:f0::1]:5683" with
Uri-Path: "temp", the full resolution steps without any shortcuts
are:
B.1.1. Resolving the URIs
The client parses the single returned record. The link's target
(sometimes called "href") is ""/temp"", which is a relative URI that
needs resolving. As long as all involved links follow the
restrictions set forth for this document (see Appendix B.4), the base
URI to resolve this against the requested URI.
The URI of the requested resource can be composed by following the
steps of [RFC7252] section 6.5 (with an addition at the end of 8.2)
into ""coap://[2001:db8:f0::1]/.well-known/core"".
Shelby, et al. Expires January 3, 2019 [Page 73]
Internet-Draft CoRE Resource Directory July 2018
The record's target is resolved by replacing the path ""/.well-known/
core"" from the Base URI (section 5.2 [RFC3986]) with the relative
target URI ""/temp"" into ""coap://[2001:db8:f0::1]/temp"".
B.1.2. Interpreting attributes and relations
Some more information but the record's target can be obtained from
the payload: the resource type of the target is "temperature", and
its content type is text/plain (ct=0).
A relation in a web link is a three-part statement that the context
resource has a named relation to the target resource, like "_This
page_ has _its table of contents_ at _/toc.html_". In [RFC6690]
link-format documents, there is an implicit "host relation" specified
with default parameter: rel="hosts".
In our example, the context of the link is the URI of the requested
document itself. A full English expression of the "host relation"
is:
'"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource
"coap://[2001:db8:f0::1]/temp", which is of the resource type
"temperature" and can be accessed using the text/plain content
format.'
B.2. A slightly more complex example
Omitting the "rt=temperature" filter, the discovery query would have
given some more records in the payload:
</temp>;rt=temperature;ct=0,
</light>;rt=light-lux;ct=0,
</t>;anchor="/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>;anchor="/sensors/temp";
rel="describedby"
Parsing the third record, the client encounters the "anchor"
parameter. It is a URI relative to the document's Base URI and is
thus resolved to ""coap://[2001:db8:f0::1]/sensors/temp"". That is
the context resource of the link, so the "rel" statement is not about
the target and the document Base URI any more, but about the target
and that address.
Thus, the third record could be read as
""coap://[2001:db8:f0::1]/sensors/temp" has an alternate
representation at "coap://[2001:db8:f0::1]/t"".
Shelby, et al. Expires January 3, 2019 [Page 74]
Internet-Draft CoRE Resource Directory July 2018
The fourth record can be read as ""coap://[2001:db8:f0::1]/sensors/
temp" is described by "http://www.example.com/sensors/t123"".
B.3. Enter the Resource Directory
The resource directory tries to carry the semantics obtainable by
classical CoAP discovery over to the resource lookup interface as
faithfully as possible.
For the following queries, we will assume that the simple host has
used Simple Registration to register at the resource directory that
was announced to it, sending this request from its UDP port
"[2001:db8:f0::1]:6553":
POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1
The resource directory would have accepted the registration, and
queried the simple host's ".well-known/core" by itself. As a result,
the host is registered as an endpoint in the RD with the name
"simple-host1". The registration is active for 90000 seconds, and
the endpoint registration Base URI is ""coap://[2001:db8:f0::1]/""
because that is the address the registration was sent from (and no
explicit "con=" was given).
If the client now queries the RD as it would previously have issued a
multicast request, it would go through the RD discovery steps by
fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd-
lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the
resource lookup endpoint, and issue a request to
"coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive
the following data:
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
anchor="coap://[2001:db8:f0::1]"
This is not _literally_ the same response that it would have received
from a multicast request, but it would contain the (almost) same
statement:
'"coap://[2001:db8:f0::1]" is hosting the resource
"coap://[2001:db8:f0::1]/temp", which is of the resource type
"temperature" and can be accessed using the text/plain content
format.'
(The difference is whether "/" or "/.well-known/core" hosts the
resources, which is subject of ongoing discussion about RFC6690).
Shelby, et al. Expires January 3, 2019 [Page 75]
Internet-Draft CoRE Resource Directory July 2018
To complete the examples, the client could also query all resources
hosted at the endpoint with the known endpoint name "simple-host1".
A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1"
would return
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0;
anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/t>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby"
All the target and anchor references are already in absolute form
there, which don't need to be resolved any further.
Had the simple host registered with an explicit context (eg.
"?ep=simple-host1&con=coap+tcp://simple-host1.example.com"), that
context would have been used to resolve the relative anchor values
instead, giving
<coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0;
anchor="coap+tcp://simple-host1.example.com"
and analogous records.
B.4. A note on differences between link-format and Link headers
While link-format and Link headers look very similar and are based on
the same model of typed links, there are some differences between
[RFC6690] and [RFC5988], which are dealt with differently:
o "Resolving the target against the anchor": [RFC6690] Section 2.1
states that the anchor of a link is used as the Base URI against
which the term inside the angle brackets (the target) is resolved,
falling back to the resource's URI with paths stripped off (its
"Origin"). [RFC8288] Section B.2 describes that the anchor is
immaterial to the resolution of the target reference.
RFC6690, in the same section, also states that absent anchors set
the context of the link to the target's URI with its path stripped
off, while according to [RFC8288] Section 3.2, the context is the
resource's base URI.
In the context of a Resource Directory, the authors decided not to
not let this become an issue by requiring that RFC6690 links be
serialized in a way that either rule set can be applied and give
Shelby, et al. Expires January 3, 2019 [Page 76]
Internet-Draft CoRE Resource Directory July 2018
the same results. Note that all examples of [RFC6690], [RFC8288]
and this document comply with that rule.
The Modernized Link Format is introduced in Appendix D to
formalize what it means to apply the ruleset of RFC8288 to Link
Format documents.
o There is no percent encoding in link-format documents.
A link-format document is a UTF-8 encoded string of Unicode
characters and does not have percent encoding, while Link headers
are practically ASCII strings that use percent encoding for non-
ASCII characters, stating the encoding explicitly when required.
For example, while a Link header in a page about a Swedish city
might read
"Link: </temperature/Malm%C3%B6>;rel="live-environment-data""
a link-format document from the same source might describe the
link as
"</temperature/Malmoe>;rel="live-environment-data""
Parsers and producers of link-format and header data need to be
aware of this difference.
Appendix C. Syntax examples for Protocol Negotiation
[ This appendix should not show up in a published version of this
document. ]
The protocol negotiation that is being worked on in
[I-D.silverajan-core-coap-protocol-negotiation] makes use of the
Resource Directory.
Until that document is update to use the latest resource-directory
specification, here are some examples of protocol negotiation with
the current Resource Directory:
An endpoint could register as follows from its address
"[2001:db8:f1::2]:5683":
Shelby, et al. Expires January 3, 2019 [Page 77]
Internet-Draft CoRE Resource Directory July 2018
Req: POST coap://rd.example.com/rd?ep=node1
&at=coap+tcp://[2001:db8:f1::2]
Content-Format: 40
Payload:
</temperature>;ct=0;rt="temperature";if="core.s"
Res: 2.01 Created
Location-Path: /rd/1234
An endpoint lookup would just reflect the registered attributes:
Req: GET /rd-lookup/ep
Res: 2.05 Content
</rd/1234>;ep="node1";con="coap://[2001:db8:f1::2]:5683";
at="coap+tcp://[2001:db8:f1::2]"
A UDP client would then see the following in a resource lookup:
Req: GET /rd-lookup/res?rt=temperature
Res: 2.05 Content
<coap://[2001:db8:f1::2]/temperature>;ct=0;rt="temperature";
if="core.s"; anchor="coap://[2001:db8:f1::2]"
while a TCP capable client could say:
Req: GET /rd-lookup/res?rt=temperature&tt=tcp
Res: 2.05 Content
<coap+tcp://[2001:db8:f1::2]/temperature>;ct=0;rt="temperature";
if="core.s";anchor="coap+tcp://[2001:db8:f1::2]"
Appendix D. Modernized Link Format parsing
The CoRE Link Format as described in [RFC6690] is unsuitable for some
use cases of the Resource Directory, and their resolution scheme is
often misunderstood by developers familiar with [RFC8288].
For the correct application of base URIs, we describe the
interpretation of a Link Format document as a Modernized Link Format.
In Modernized Link Format, the document is processed as in Link
Format, with the exception of Section 2.1 of [RFC6690]:
o The URI-reference inside angle brackets ("<>") describes the
target URI of the link. If it is a relative reference, it is
resolved against the base URI of the document.
Shelby, et al. Expires January 3, 2019 [Page 78]
Internet-Draft CoRE Resource Directory July 2018
o The context of the link is expressed by the "anchor" parameter; if
it is a relative reference, it is resolved against the document's
base URI. In absence of the "anchor" attribute, the base URI is
the link's context.
Content formats derived from [RFC6690] which inherit its resolution
rules, like JSON and CBOR link format of [I-D.ietf-core-links-json],
can be interpreted in analogy to that.
For where the Resource Directory is concerned, all common forms of
links (eg. all the examples of RFC6690) yield identical results.
When interpreting data read from ".well-known/core", differences in
interpretation only affect links where the absent anchor attribute
means "coap://host/" according to RFC6690 and "coap://host/.well-
known/core" according to Modernized Link format; those typically only
occur in conjunction with the vaguely defined implicit "hosts"
relationship.
D.1. For endpoint developers
When developing endpoints, ie. when generating documents that will be
submitted to a Resource Directory, the differences between Modernized
Link Format and RFC6690 can be ignored as long as all relative
references start with a slash, and any of the following applies:
o There is no anchor attribute, and the context of the link does not
matter to the application.
Example: "</sensors>;ct=40"
o The anchor is a relative reference.
Example: "</t>;anchor="/sensors/temp";rel="alternate"
o The target is an absolute reference.
Example: "<http://www.example.com/sensors/t123>;anchor="/sensors/
temp";rel="describedby""
Authors' Addresses
Shelby, et al. Expires January 3, 2019 [Page 79]
Internet-Draft CoRE Resource Directory July 2018
Zach Shelby
ARM
150 Rose Orchard
San Jose 95134
USA
Phone: +1-408-203-9434
Email: zach.shelby@arm.com
Michael Koster
SmartThings
665 Clyde Avenue
Mountain View 94043
USA
Phone: +1-707-502-5136
Email: Michael.Koster@smartthings.com
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Peter van der Stok
consultant
Phone: +31-492474673 (Netherlands), +33-966015248 (France)
Email: consultancy@vanderstok.org
URI: www.vanderstok.org
Christian Amsuess (editor)
Hollandstr. 12/4
1020
Austria
Phone: +43-664-9790639
Email: christian@amsuess.com
Shelby, et al. Expires January 3, 2019 [Page 80]