Subject: [core] Resource Directory: Use of /rd in path

From: Hannes Tschofenig <[email-masked]>
Date: Tue, 9 Aug 2016 14:00:05 +0200

Hi RD authors, Hi all,

I have a question regarding the use of the /rd prefix in the path.

The /rd path is used in the draft in various places, sometimes in
examples (where the use of completely optional) and in other places
where the use is recommended (but not mandated). The recommendation is
stated in Section 6.3 regarding the use of the RD function set path.

It is, however, not clear where in the text it was only used as an
example and when it was used according to the recommendation.

It appears that the use of the /rd in the path is only recommended for
the registration procedure. Is this correct?

Here is the relevant example:

   Req: POST coap://rd.example.com/rd?ep=node1
                                  ^^^^^
                                    +----- recommended
   Content-Format: 40
   Payload:
   </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
   </sensors/light>;ct=41;rt="light-lux";if="sensor"

   Res: 2.01 Created
   Location: /rd/4521
            ^^^^
             +------- example only

   Req: POST /rd?ep=node1 HTTP/1.1
            ^^^^^
             +----- recommended

   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
             ^^^^
              +------- example only

Ciao
Hannes

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 09 Aug 2016 14:13:58 +0200

Hi Hannes,

it's good that you bring this up.

Section 6.2 says:

6.2.  Discovery

   Before an endpoint can make use of an RD, it must first know the RD's
   address and port, and the path of its RD Function Set. There can be

and goes on to describe how to look for the resource type "core.rd" to
find the path to the resource directory "function set" (a term that we
don't really like any more, but which will do for now -- this may be a
bit like the OAuth "endpoints"; we need to find a better term for these
sets of related resources).

I'm not quite sure what to make of the recommendation in Section 6.3 to
use "/rd" for the path that goes into the URI Template.  On one hand, a
convention like this can aid in debugging.  On the other hand,
conventions like this tend to ossify, and this turns the SHOULD into a
borderline violation of RFC 7320 (BCP 190).  I think I would be happier
to change the SHOULD into what it is, a convention, which can be
superseded by all kinds of considerations as per RFC 7320.  More
importantly, skipping the discovery step and going right for "/rd" would
be bad client behavior and should not be condonable by that SHOULD.
(The SHOULD is also making a rather implicit definition of when it can
be superseded -- whenever the convention is "impossible"?  What does
that mean...)

Grüße, Carsten

Hannes Tschofenig wrote:
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: peter van der Stok <[email-masked]>
Date: Wed, 10 Aug 2016 11:31:13 +0200

Hi Carsten,

Do I understand correctly that you recommend to keep the current 
template wording?

URI Template:  /{+rd}{?ep,d,et,lt,con}

    URI Template Variables:

       rd :=  RD Function Set path (mandatory).  This is the path of the
          RD Function Set, as obtained from discovery.  An RD SHOULD use
          the value "rd" for this variable whenever possible.

Peter

---

From: Hannes Tschofenig <[email-masked]>
Date: Wed, 10 Aug 2016 12:34:58 +0200

Hi Carsten,

I agree with you that 'function set' is probably not the best possible
term and maybe there is a chance to replace it with something else.

Regarding hard coding the path /rd instead of using discovery: I am not
necessarily against hard coding since it avoids the need of discovery,
particularly when it is unclear how often an IoT device needs to execute
this discovery step.

However, what I am less sure about is where in the document the /rd path
is actually the result of hard coding vs. just used in as an example.

Ciao
Hannes

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 10 Aug 2016 13:39:28 +0200

>          the value "rd" for this variable whenever possible.

Maybe a better wording of the last sentence would be:

As a convention that aids in debugging, a server can use the value "rd"
unless it prefers a different value.

Gets rid of the SHOULD, and makes it clear the the server is free to
choose (as per RFC 7320).

(And maybe we can get rid of "Function Set" in a separate effort.)

Grüße, Carsten

---

From: peter van der Stok <[email-masked]>
Date: Wed, 10 Aug 2016 17:40:19 +0200

Hi Carsten,

Thanks for the suggestions, but the changes do not look that essential 
for the iteroperability and implementation to me.
I would prefer to get the draft out as is.
Hannes thinks differently?

Peter

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 11 Aug 2016 08:31:11 +0200

Hi Peter,

I only want to have clarify what use of /rd is there in the examples
because of the recommendation and what has been chosen for convenience.

Ciao
Hannes

---

From: peter van der Stok <[email-masked]>
Date: Tue, 16 Aug 2016 09:35:55 +0200

Hi Hannes, Carsten,

I will provide a phrase in the RD draft that the use of the path "/rd" 
in all examples is the convention used for the RD path in this draft.

Concerning the template I propose:

  rd :=  RD Function Set path (mandatory).  This is the path of the
       RD Function Set, as obtained from discovery.  The value "rd" is 
used as an example value throughout this document

and as a side:
Replace RD Function Set path by: RD container path?

Greetings,

Peter

---

From: Michael Koster <[email-masked]>
Date: Tue, 16 Aug 2016 16:41:48 -0700

Hi,

We define three "function sets" in RD. They are Registration (rt=core.rd), Lookup (rt=core.rd-lookup) and Group (rt=core.rd-group). Each of these has an API entry URI that we suggest conventional usage of /rd, /rd-lookup, and /rd-group

Whatever we do to improve the terminology from "function set" to "REST API entry point" or whatever we choose, it needs to be done consistently in the document for all 3 cases.

I don't think "container path" is necessarily a better choice. 

Hannes, Carsten, anyone, do you have a suggestion for what we should call these different API entry points? 

Best regards,

Michael

> On Aug 16, 2016, at 12:35 AM, peter van der Stok <[email-masked]> wrote:
> 
> Hi Hannes, Carsten,
> 
> I will provide a phrase in the RD draft that the use of the path "/rd" in all examples is the convention used for the RD path in this draft.
> 
>      RD Function Set, as obtained from discovery.  The value "rd" is used as an example value throughout this document
> 
> and as a side:

---

From: "Kovatsch, Matthias" <[email-masked]>
Date: Fri, 26 Aug 2016 11:19:59 +0000

Hi

My suggestion: These are three different RESTful service entry points. So depending on what exactly we are talking about, we have:

- entry point URI (e.g., coap:/rd.example.com/rd)
- entry point resource (e.g., /rd of a specific server)

A more explicit version would be to call it "service entry point URI/resource" all the time.

Ciao
Matthias

> -----Ursprüngliche Nachricht-----
> Von: core [mailto:[email-masked]] Im Auftrag von Michael Koster
> Gesendet: Mittwoch, 17. August 2016 01:42
> An: [email-masked]
> Cc: [email-masked] WG
> Betreff: Re: [core] Resource Directory: Use of /rd in path
> 
> Hi,
> 
> We define three "function sets" in RD. They are Registration (rt=core.rd), Lookup
> (rt=core.rd-lookup) and Group (rt=core.rd-group). Each of these has an API entry
> URI that we suggest conventional usage of /rd, /rd-lookup, and /rd-group
> 
> Whatever we do to improve the terminology from "function set" to "REST API
> entry point" or whatever we choose, it needs to be done consistently in the
> document for all 3 cases.
> 
> > I will provide a phrase in the RD draft that the use of the path "/rd" in all
> examples is the convention used for the RD path in this draft.
> >
> >>> Thanks for the suggestions, but the changes do not look that
> >>> essential for the iteroperability and implementation to me.
> >>>> Gets rid of the SHOULD, and makes it clear the the server is free
> >>>> to choose (as per RFC 7320).

---

From: peter van der Stok <[email-masked]>
Date: Mon, 29 Aug 2016 08:58:59 +0200

Hi Matthias,

Understood your suggestion for the individual entry points.
But how to call the set of related entry points URI/resource?

BTW it is possible to define abbreviations or acronyms in the beginning 
of the document;
so that would be "service ep URI/resource" or even shorter?

Peter

Kovatsch, Matthias schreef op 2016-08-26 13:19:
> Hi
> 
> My suggestion: These are three different RESTful service entry points.
> So depending on what exactly we are talking about, we have:
> 
>> Hannes, Carsten, anyone, do you have a suggestion for what we should 
>> call these
>> different API entry points?
>> 
>> Best regards,
>> 
>> Michael
>> 
>>

---

From: "Kovatsch, Matthias" <[email-masked]>
Date: Mon, 29 Aug 2016 11:54:30 +0000

Dear Peter

> But how to call the set of related entry points URI/resource?

I would say we have three RESTful services with multiple resources each:

- registration service with registration resources
- lookup service with lookup resources
- group management service with group (management) resources

> BTW it is possible to define abbreviations or acronyms in the beginning of the
> document; so that would be "service ep URI/resource" or even shorter?

We need to be careful with "ep" which primarily stands for endpoint in CoRE.

The whole naming with "function sets" came from the tight relation with the early days of IPSO Objects when Zach was highly active in all of this. The long-term goal is constrained RESTful environments, thus I would stick with RESTful Web service terminology. When we introduce the RD to provide three RESTful Web services for registration, lookup, and group management, the explanations with entry points for each of these services, which in turn consist of a number of service-specific resources, will become clearer and more self-explanatory.

To make this really viable and future-proof, we need to provide links and forms at the entry point URIs in the future (i.e., return them when doing a GET on these resources). For this, we started the "Resource directory evolution" thread a while ago.

Ciao
Matthias

> >> (rt=core.rd-lookup) and Group (rt=core.rd-group). Each of these has
> >> an API entry URI that we suggest conventional usage of /rd,
> >> /rd-lookup, and /rd-group
> >>
> >> Whatever we do to improve the terminology from "function set" to
> >> "REST API entry point" or whatever we choose, it needs to be done
> >> consistently in the document for all 3 cases.
> >>
> >> call these different API entry points?
> >>
> >> Best regards,
> >>
> >> Michael
> >>
> >>
> >> >      RD Function Set, as obtained from discovery.  The value "rd"
> >> > is used as an example value throughout this document
> >> >
> >> > and as a side:
> >> >> I only want to have clarify what use of /rd is there in the
> >> >> examples because of the recommendation and what has been chosen for
> convenience.
> >> >> Ciao
> >> >> Hannes
> >> >>>>> Do I understand correctly that you recommend to keep the
> >> >>>>> current template wording?
> >> >>>> Gets rid of the SHOULD, and makes it clear the the server is
> >> >>>> free to choose (as per RFC 7320).
> >> >>>> (And maybe we can get rid of "Function Set" in a separate
> >> >>>> effort.) Grüße, Carsten
> >> >