Draft: draft-ietf-core-resource-directory

Commentary: I registree - ep , because the text is not always clear which endpoint or CT ( client ) is doing the registration . Also changed endpoint to registration for some phrases 
 I 've played with the thought of renaming " endpoints " to " registrations " and discarded it for causing more confusion , but " registree endpoint " sounds good and descriptive . Do you want to wait for other authors ' comments on it or shall we just merge it ? 
 On first reading the proposed change I probably misunderstood its intention ( I thought it 'd refer to the registration the endpoint obtains ( linked to the registration resource ) and not the endpoint - as - in - coap - terms -- but that was careless patch - reading of mine . Nonetheless , clearer terminology is something we should have , and this can be a step towards it . 
 it is the ep to be registered . In the text it is not always clear what is registered and what is doing the registering . I exchanged endpoint with registry when endpoint was misused . Also client and server are ambiguous terms sometimes . For me it can be merged . Probably you will find other examples in the text where ep , rg or cl - s are overloaded or just wrong ..  chrysn schreef op 2018 - 06 - 18 17:02 : Links : [ 1 ] [ 2 ]
Paragraph (version B):
Registree-ep is the endpoint that is registered into the RD.  The
registree-ep can register itself, or a CT registers the registree-
ep.
Paragraph (version A):
Endpoint name (mostly mandatory).  The endpoint name is an
identifier that MUST be unique within a domain.  The maximum
length of this parameter is 63 bytes.  If the RD is configured
to recognize the endpoint (eg. based on its security context),
the endpoint can ignore the endpoint name, and assign one based
on a se of configuration parameter values.
Paragraph (version B):
Endpoint name (mostly mandatory).  The endpoint name is an
identifier that MUST be unique within a domain.  The maximum
length of this parameter is 63 bytes.  If the RD is configured
to recognize the endpoint (eg. based on its security context),
the endpoint can ignore the endpoint name, and assign one based
on a set of configuration parameter values.
Paragraph (version A):
The following example shows an endpoint with the name "node1"
registering two resources to an RD using this interface.  The
location "/rd" is an example RD location discovered in a request
similar to example-discovery.
Paragraph (version B):
The following example shows a registree-ep with the name "node1"
registering two resources to an RD using this interface.  The
location "/rd" is an example RD location discovered in a request
similar to example-discovery.
Paragraph (version A):
Not all endpoints hosting resources are expected to know how to
upload links to a RD as described in registration.  Instead, simple
endpoints can implement the Simple Registration approach described in
this section.  An RD implementing this specification MUST implement
Simple Registration.  However, there may be security reasons why this
form of directory discovery would be disabled.
Paragraph (version A):
This approach requires that the endpoint makes available the hosted
resources that it wants to be discovered, as links on its "/.well-
known/core" interface as specified in RFC6690.  The links in that
document are subject to the same limitations as the payload of a
registration (no relative target references when anchor is present).
Paragraph (version A):
The endpoint then finds one or more addresses of the directory server
as described in finding_an_rd.
Paragraph (version A):
The endpoint sends (and regularly refreshes with) a POST request to
the "/.well-known/core" URI of the directory server of choice.  The
body of the POST request is empty, which triggers the resource
directory server to perform GET requests at the requesting server's
default discovery URI to obtain the link-format payload to register.
Paragraph (version A):
The endpoint includes the same registration parameters in the POST
request as it would per registration.  The context of the
registration is taken from the requesting server's URI.
Paragraph (version B):
Not all endpoints hosting resources are expected to know how to
upload links to an RD as described in registration.  Instead, simple
endpoints can implement the Simple Registration approach described in
this section.  An RD implementing this specification MUST implement
Simple Registration.  However, there may be security reasons why this
form of directory discovery would be disabled.
Paragraph (version B):
This approach requires that the registree-ep makes available the
hosted resources that it wants to be discovered, as links on its
"/.well-known/core" interface as specified in RFC6690.  The links in
that document are subject to the same limitations as the payload of a
registration (no relative target references when anchor is present).
Paragraph (version B):
The registree-ep then finds one or more addresses of the directory
server as described in finding_an_rd.
Paragraph (version B):
The regsitree-ep sends (and regularly refreshes with) a POST request
to the "/.well-known/core" URI of the directory server of choice.
The body of the POST request is empty, which triggers the resource
directory server to perform GET requests at the requesting registree-
ep's default discovery URI to obtain the link-format payload to
register.
Paragraph (version B):
The registree-ep includes the same registration parameters in the
POST request as it would per registration.  The context of the
registration is taken from the requesting server's URI.
Paragraph (version A):
The endpoints MUST be deleted after the expiration of their lifetime.
Additional operations on the registration resource cannot be executed
because no registration location is returned.
Paragraph (version A):
The following example shows an endpoint using Simple Registration, by
simply sending an empty POST to a resource directory.
Paragraph (version B):
The registration resources MUST be deleted after the expiration of
their lifetime.  Additional operations on the registration resource
cannot be executed because no registration location is returned.
Paragraph (version B):
The following example shows a registree-ep using Simple Registration,
by simply sending an empty POST to a resource directory.
Paragraph (version A):
In a controlled environment (e.g. building control), the Resource
Directory can be filled by a third device, called a commissioning
tool.  The commissioning tool can fill the Resource Directory from a
database or other means.  For that purpose the scheme, IP address and
port of the registered device is indicated in the Context parameter
of the registration described in registration.
Paragraph (version B):
In a controlled environment (e.g. building control), the Resource
Directory can be filled by a third party device, called a
commissioning tool.  The commissioning tool can fill the Resource
Directory from a database or other means.  For that purpose the
scheme, IP address and port of the registered device is indicated in
the Context parameter of the registration described in registration.
Paragraph (version A):
If the registration update fails with a "Service Unavailable"
response and a Max-Age option or Retry-After header, the client
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 client SHOULD
attempt registration again.
Paragraph (version B):
If the registration update fails with a "Service Unavailable"
response and a Max-Age option or Retry-After header, the 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 endpoint
SHOULD attempt registration again.
Paragraph (version A):
Although RD entries have soft state and will eventually timeout after
their lifetime, an endpoint SHOULD explicitly remove its 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.
Paragraph (version A):
Removed endpoints are implicitly removed from the groups to which
they belong.
Paragraph (version B):
Although RD entries have soft state and will eventually timeout after
their lifetime, an 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.
Paragraph (version B):
Removed registrations are implicitly removed from the groups to which
they belong.