Draft: draft-ietf-core-resource-directory

Commentary: in particular : resource naming , group creation , changelog 
 That 's correct . an directory resource is created , unless already present , such that the registration resources can be created . Other text wanted ? chrysn schreef op 2017 - 10 - 24 15:15 : 
 I 'd just leave the line in question as it was . 
 Granted , I do n't really understand what purpose the plurality definition serves , but a clarification in ( " ... within the directory resource " ) brings this up : If ( as it is currently defined ) plurality is checked between any two links in the whole RD , any two registrations that contain a static statement between external URIs ( like the one in A.2 ) creates link plurality . Such links are perfectly legal in a .well - known / core document , so why should they not be permissible in an RD ? Assigning because your change triggered this , but feel free to reassign to whoever understands plurality best ( I do n't remember who introduced the concept ) . 
 I introduced the concept , based on a request , to deal with the idea that there may be accidentally duplicated links in an RD as an error condition . I 'm not sure it is an error to have two links exactly the same , but there may be errors that result in failure to remove old links , etc that resut in duplicates . I think  was also involved ; is there any other concern ? Perhaps this could be removed now that we have a better understanding . Best regards ,    that there are all kinds of permissible .well - known / core contents , I think it 's hard to describe any constraints here that correctly indicate an implementation or usage error without precluding valid use cases . IMO this would be better handled at the PATCH / iPATCH - for - link - format specification , where the more concrete measures can be taken . The only place where what this tries to catch can happen with the current document is at a POST to the registration resource . Would being clear that a POST must not be considered idempotent here suffice ? 
 That 's awkward , as elsewhere it is stated that all functions on RD MUST be idem - potent  chrysn schreef op 2017 - 10 - 24 15:31 : 
 I 'm happy about removing . It is indeed at the PATCH that things get complicated , but that will be solved by the media type format I expect .    schreef op 2017 - 10 - 24 15:16 : 
 Agree to remove and deal with the potential issue in the PATCH discussion    is idempotent , ie . POSTing to the directory resource . Updating a registration with new links , ie . POSTing to the registration resource , results in plurality . 
 but remains idem - potent ? That means that the same ep with identical attributes can be an infinite number of times . A note about uniqueness of ep name should take care of that problem ?  chrysn schreef op 2017 - 10 - 24 18:08 : 
 No , adding an endpoint is registration . That 's idempotent , and " keyed " to domain and endpoint name . A , done repeatedly , always returns , and will contain exactly once the links sent in the POST 's payload , because it was and is described as idempotent . A subsequent with additional links is the part that is affected by plurality . That is not idempotent on a REST level ( because the first returns and the second returns ) , but is idempotent at application level because the plurality check keeps the link from being . Unfortunately , the same rules forbid simple registration of nodes whose states ( in bad style , but IMO legally ) , or ( which is the original topic of this issue ) two registering resources from both claiming . At least the latter ( and I 'd argue also the former ) is too strict , and catches errors only at the expense of not allowing full replication any more . 
 Is it OK for you , if I change text to remove parts and improve the addition problems ? I have an hour this weekend 
 Sure , go ahead , I 'll probably only continue on it on Monday . 
 made new version that suppressed text on plurality of links . conflict : when registration is creted with duplicate ep , d , values . Addition of link in registration : Do nothing when fully identical links already exists .
Paragraph (version B):
A resource in the Resource Directory (RD) containing registration
resources.
Paragraph (version B):
A resource in the RD containing registration repources of the
Endpoints that form a group.
Paragraph (version B):
A resource in the RD that contains information about an Endpoint
and its links.
Paragraph (version A):
The resource directory architecture is illustrated in fig-arch.  A
Resource Directory (RD) is used as a repository for Web Links RFC5988
about resources hosted on other web servers, which are called
endpoints (EP).  An endpoint is a web server associated with a
scheme, IP address and port (called Context), thus a physical node
may host one or more endpoints.  The RD implements a set of REST
interfaces for endpoints to register and maintain sets of Web Links
(called resource directory registration entries), and for clients to
lookup resources from the RD or maintain groups.  Endpoints
themselves can also act as clients.  An RD can be logically segmented
by the use of Domains.  The domain an endpoint is associated with can
be defined by the RD or configured by an outside entity.  This
information hierarchy is shown in fig-hierarchy.
Paragraph (version B):
The resource directory architecture is illustrated in fig-arch.  A
Resource Directory (RD) is used as a repository for Web Links RFC5988
about resources hosted on other web servers, which are called
endpoints (EP).  An endpoint is a web server associated with a
scheme, IP address and port, thus a physical node may host one or
more endpoints.  The RD implements a set of REST interfaces for
endpoints to register and maintain sets of Web Links (called resource
directory registration entries), and for clients to lookup resources
from the RD or maintain groups.  Endpoints themselves can also act as
clients.  An RD can be logically segmented by the use of Domains.
The domain an endpoint is associated with can be defined by the RD or
configured by an outside entity.  This information hierarchy is shown
in fig-hierarchy.
Paragraph (version A):
An endpoint is provided with interfaces to register, update and
remove a resource directory registration entry.  It is also possible
for an RD to fetch Web Links from endpoints and add them as resource
directory entries.
Paragraph (version A):
At the first registration of a set of entries, a "registration
resource" is created, the location of which is returned to the
registering endpoint.  The registering endpoint uses this
registration resource to manage the contents of the registration
entry.
Paragraph (version B):
An endpoint is provided with interfaces to register, update and
remove a resource directory registration entry.  It is also possible
for an RD to fetch Web Links from endpoints and add them as resource
directory registration entries.
Paragraph (version B):
At the first registration of a set of entries, a "directory resource"
is created, the location of which is returned to the registering
endpoint.  The registering endpoint uses this registration resource
to manage the contents of the registration entry.
Paragraph (version A):
The Entity-Relationship (ER) models shown in fig-ER-WKC and fig-ER-RD
model the contents of /.well-known/core and the resource directory
respectively, with entity-relationship diagrams ER.  Entities
(rectangles) are used for concepts that exist independently.
Attributes (ovals) are used for concepts that exist only in
connection with a related entity.  Relations (diamonds) give a
semantic meaning to the relation between entities.  Numbers specify
the cardinality of the relations.  The relations between the values
of the attributes are explained in the interface sections.
Paragraph (version B):
The Entity-Relationship (ER) models shown in fig-ER-WKC and fig-ER-RD
model the contents of /.well-known/core and the resource directory
respectively, with entity-relationship diagrams ER.  Entities
(rectangles) are used for concepts that exist independently.
Attributes (ovals) are used for concepts that exist only in
connection with a related entity.  Relations (diamonds) give a
semantic meaning to the relation between entities.  Numbers specify
the cardinality of the relations.
Paragraph (version A):
The cardinality of con is currently 1 (n2 = 1).  The value of con is
copied from the value of the "hosts" relation and overwritten by the
value of the con query parameter.
Paragraph (version B):
The cardinality of con is currently 1.  The value of con is copied
from the value of the "hosts" relation and overwritten by the value
of the con query parameter.
Paragraph (version B):
It may be configured to use a service discovery mechanism such as
DNS-SD RFC6763.  The present specification suggests configuring
the service with name rd._sub._coap._udp, preferably within the
domain of the querying nodes.
Paragraph (version A):
The following example shows an endpoint discovering an RD using this
interface, thus learning that the RD registration resource is, in
this example, at /rd, and that the content-format delivered by the
server hosting the resource is application/link-format (ct=40).  Note
that it is up to the RD to choose its RD resource paths.
Paragraph (version B):
The following example shows an endpoint discovering an RD using this
interface, thus learning that the directory resource is, in this
example, at /rd, and that the content-format delivered by the server
hosting the resource is application/link-format (ct=40).  Note that
it is up to the RD to choose its RD resource paths.
Paragraph (version A):
The following example shows the way of indicating that a client may
request alternate content-formats.  The Content-Format code attribute
"ct" MAY include a space-separated sequence of Content-Format codes
as specified in Section 7.2.1 of RFC7252, indicating that multiple
content-formats are available.  The example below shows the required
Content-Format 40 (application/link-format) indicated as well as a
more application-specific content format (picked as 65225 in this
example; this is in the experimental space, not an assigned value).
The RD resource paths /rd, /rd-lookup, and /rd-group are example
values.  This server only implements some of the interfaces described
in this document.
Paragraph (version B):
The following example shows the way of indicating that a client may
request alternate content-formats.  The Content-Format code attribute
"ct" MAY include a space-separated sequence of Content-Format codes
as specified in Section 7.2.1 of RFC7252, indicating that multiple
content-formats are available.  The example below shows the required
Content-Format 40 (application/link-format) indicated as well as a
more application-specific content format (picked as 65225 in this
example; this is in the experimental space, not an assigned value).
The RD resource paths /rd, /rd-lookup, and /rd-group are example
values.
Paragraph (version A):
Endpoint resources in the RD are kept active for the period indicated
by the lifetime parameter.  The endpoint is responsible for
refreshing the entry within this period using either the registration
or update interface.  The registration interface MUST be implemented
to be idempotent, so that registering twice with the same endpoint
parameters ep and d does not create multiple RD entries.  A new
registration may be created at any time to supersede an existing
registration, replacing the registration parameters and links.
Paragraph (version A):
The posted link-format document can (and typically does) contain
relative references both in its link targets and in its anchors, or
contain empty anchors.  The server needs to resolve these references
in order to faithfully represent them in lookups.  The Base URI
against which they are resolved is the context of the registration,
which is provided either explicitly in the "con" parameter or
constructed implicitly from the requester's network address.  When
resolving relative target references, the server first resolves the
context of that link (the in the "anchor" attribute), and then
interprets the target as a reference relative to that context (see
resolution-rules).
Paragraph (version B):
Registration resources in the RD are kept active for the period
indicated by the lifetime parameter.  The endpoint is responsible for
refreshing the registration resource within this period using either
the registration or update interface.  The registration interface
MUST be implemented to be idempotent, so that registering twice with
the same endpoint parameters ep and d does not create multiple
registration resources.  A new registration resource may be created
at any time to supersede an existing registration, replacing the
registration parameters and links.
Paragraph (version B):
The posted link-format document can (and typically does) contain
relative references both in its link targets and in its anchors, or
contain empty anchors.  The RD server needs to resolve these
references in order to faithfully represent them in lookups.  The
Base URI against which they are resolved is the context of the
registration, which is provided either explicitly in the "con"
parameter or constructed implicitly from the requester's network
address.  When resolving relative target references, the server first
resolves the context of that link, and then interprets the target as
a reference relative to that context (see resolution-rules).
Paragraph (version A):
Context (optional).  This parameter sets the Default Base URI
under which the request's body are be interpreted.  The URI
scheme provided MUST allow a path component, but the path
component of the Context parameter MUST be empty.  The
parameter is therefore of the shape "scheme://authority" for
HTTP and CoAP URIs.  In the absence of this parameter the
scheme of the protocol, source address and source port of the
register request are assumed.  This parameter is mandatory when
the directory is filled by a third party such as an
commissioning tool.  If the endpoint uses an ephemeral port to
register with, it MUST include the con parameter in the
registration to provide a valid network path.  If the endpoint
which is located behind a NAT gateway is registering with a
Resource Directory which is on the network service side of the
NAT gateway, the endpoint MUST use a persistent port for the
outgoing registration in order to provide the NAT gateway with
a valid network address for replies and incoming requests.
Paragraph (version B):
Context (optional).  This parameter sets the Default Base URI
under which the request's links are to be interpreted.  The URI
MUST NOT have a path component of its own, but MUST be suitable
as a base URI to resolve any relative references given in the
registration.  The parameter is therefore of the shape
"scheme://authority" for HTTP and CoAP URIs.  In the absence of
this parameter the scheme of the protocol, source address and
source port of the registration request are assumed.  This
parameter is mandatory when the directory is filled by a third
party such as an commissioning tool.  If the endpoint uses an
ephemeral port to register with, it MUST include the con
parameter in the registration to provide a valid network path.
If the endpoint which is located behind a NAT gateway is
registering with a Resource Directory which is on the network
service side of the NAT gateway, the endpoint MUST use a
persistent port for the outgoing registration in order to
provide the NAT gateway with a valid network address for
replies and incoming requests.
Paragraph (version A):
A Resource Directory SHOULD reject a registration, or an operation on
a registration, which would result in a plurality of link references
within the the context of the Resource Directory.  There is no
requirement in this document for a resource directory to check for
plurality of reference.  Resource Directory operations which are
rejected due to reference plurality SHOULD be returned the "Conflict"
code, indicating that there is someting wrong with the request.
Paragraph (version B):
A Resource Directory SHOULD reject a registration, or an operation on
a registration resource, which would result in a plurality of link
references within the directory resource.  There is no requirement in
this document for a resource directory to check for plurality of
reference.  Resource Directory operations which are rejected due to
reference plurality SHOULD return the "Conflict" code, indicating
that there is someting wrong with the request.
Paragraph (version A):
After the initial registration, an endpoint should retain 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 with information from the 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 resource recovery and
garbage collection.  If the Registration Resource is removed, the
endpoint will need to re-register.
Paragraph (version A):
The Registration Resource may also be used to inspect the
registration resource using GET, update the registration link
contents using iPATCH or PATCH (as introduced in RFC8132), or cancel
the registration using DELETE.
Paragraph (version B):
After the initial registration, an endpoint should retain 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 resource recovery and
garbage collection.  If the Registration Resource is removed, the
endpoint will need to re-register.
Paragraph (version B):
The Registration Resource may also be used to inspect the
registration resource using GET, update the registration link
contents, or cancel the registration using DELETE.
Paragraph (version A):
TODO: suggestion to do a GET /rd to obtain a list of registrations
loc, ep,...
Paragraph (version A):
An update MAY update the lifetime or context registration parameters
"lt", "con" as in registration.  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 registration.
Paragraph (version B):
An update MAY update the lifetime- or the context- registration
parameters "lt", "con" as in registration.  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 registration.
Paragraph (version A):
The following example shows an endpoint updating its registration at
an RD using this interface with the example location value: /rd/4521.
Paragraph (version B):
The following example shows an endpoint updating its registration
resource at an RD using this interface with the example location
value: /rd/4521.
Paragraph (version A):
Context (optional).  This parameter sets the scheme, address
and port at which this server is available in the form
scheme://host:port/path.  In the absence of this parameter the
scheme of the protocol, source address and source port of the
register request are assumed.  This parameter is mandatory when
the directory is filled by a third party such as an
commissioning tool.  When con is used, scheme and host are
mandatory and port and path parameters are optional.
Paragraph (version B):
Context (optional).  This parameter sets the scheme, address
and port of the multicast address associated with the group.
When con is used, scheme and host are mandatory and port
parameter is optional.
Paragraph (version A):
be returned in response to a successful group CREATE operation.
This Location MUST be a stable identifier generated by the RD as
it is used for delete operations of the group registration
resource.
Paragraph (version B):
be returned in response to a successful group CREATE operation.
This Location MUST be a stable identifier generated by the RD as
it is used for delete operations of the group resource.
Paragraph (version A):
The following example shows an EP registering a group with the name
"lights" which has two endpoints to an RD using this interface.  The
RD group path /rd-group is an example RD location discovered in a
request similar to example-discovery.
Paragraph (version B):
The following example shows an EP registering a group with the name
"lights" which has two endpoints.  The RD group path /rd-group is an
example RD location discovered in a request similar to example-
discovery.
Paragraph (version B):
The href value is the path to the registration resource of the
Endpoint.
Paragraph (version A):
This is the Location returned by the RD as a result of a
successful group registration.
Paragraph (version B):
This is the path of the group resource returned by the RD as a
result of a successful group registration.
Paragraph (version A):
In order for an RD to be used for discovering resources registered
with it, a lookup interface must be provided.  This lookup interface
is defined as a default, and it is assumed that RDs may also support
lookups to return resource descriptions in alternative formats (e.g.
Atom or HTML Link) or using more advanced interfaces (e.g. supporting
context or semantic based lookup).
Paragraph (version B):
To discover the resources registered with the RD, a lookup interface
must be provided.  This lookup interface is defined as a default, and
it is assumed that RDs may also support lookups to return resource
descriptions in alternative formats (e.g.  Atom or HTML Link) or
using more advanced interfaces (e.g. supporting context or semantic
based lookup).
Paragraph (version A):
That allows the client to interpret the response as links without any
further knowledge of what the RD does.  The Resource Directory MAY
replace the contexts with a configured intermediate proxy, e.g. in
the case of an HTTP lookup interface for CoAP endpoints.
Paragraph (version B):
Above rules allow the client to interpret the response as links
without any further knowledge of what the RD does.  The Resource
Directory MAY replace the contexts with a configured intermediate
proxy, e.g. in the case of an HTTP lookup interface for CoAP
endpoints.
Paragraph (version A):
An Endpoint is determined to be unique by an RD by the Endpoint
identifier parameter included during Registration, and any associated
TLS or DTLS security bindings.  An Endpoint MUST NOT be identified by
its protocol, port or IP address as these may change over the
lifetime of an Endpoint.
Paragraph (version B):
An Endpoint is determined to be unique within (the domain of) an RD
by the Endpoint identifier parameter included during Registration,
and any associated TLS or DTLS security bindings.  An Endpoint MUST
NOT be identified by its protocol, port or IP address as these may
change over the lifetime of an Endpoint.
Paragraph (version A):
Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup.