Subject: Re: [Netconf] RESTCONF and draft-ietf-appsawg-uri-get-off-my-lawn-04 (on the IESG telechat this week)

From: Kent Watsen <[email-masked]>
Date: Tue, 22 Jul 2014 17:42:23 +0000

Hi Mark,

Thank you for meeting with Andy, Bert, and myself yesterday.   We're happy that you support our use of /.well-known/host-meta as described here: http://tools.ietf.org/html/draft-ietf-netconf-restconf-01#section-3.2.    Thank you also for suggesting the draft advise clients to cache the result using standard HTTP caching, we'll be sure to update the accordingly.

Thanks again,
Kent

From: Kent Watsen <[email-masked]<mailto:[email-masked]>>
Date: Thursday, May 15, 2014 at 11:21 AM
To: Benoit Claise <[email-masked]<mailto:[email-masked]>>, Andy Bierman <[email-masked]<mailto:[email-masked]>>
Cc: Mark Nottingham <[email-masked]<mailto:[email-masked]>>, 'Barry Leiba' <[email-masked]<mailto:[email-masked]>>, NetConf <[email-masked]<mailto:[email-masked]>>
Subject: Re: [Netconf] RESTCONF and draft-ietf-appsawg-uri-get-off-my-lawn-04 (on the IESG telechat this week)

Hi Mark, thanks for looking in on this!

Currently RESTCONF hardcodes the top-level URL path "/restconf", which isn't in line with your BCP.    Our thoughts are to put in text like that below.  Looking at rfc6570, I don't see how URI templates would help here.  Can you suggest a better way?  - or were you thinking that we could use URI Templates to define the structure of the RESTCONF API's URLs?

Thanks,
Kent

=====START=====

RESTCONF Path Resolution

   In line the best practices defined by "get-off-my-lawn", RESTCONF
   enables deployments to specify where the RESTCONF API is located.
   When first connecting to a RESTCONF server, a RESTCONF client MUST
   determine the root of the RESTCONF API.  The client discovers this
   by getting the ".well-known/host-meta" resource [RFC6415] as follows:

       Request
       -------
       GET /.well-known/host-meta users HTTP/1.1
       Host: example.com
       Accept: application/xrd+xml

       Response
       --------
       HTTP/1.1 200 OK
       Content-Type: application/xrd+xml
       Content-Length: nnn

       <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
           <Link rel='restconf' href='/api/restconf'/>
       </XRD>

   Once discovering the RESTCONF API root, the client MUST prepend it to
   any access to a RESTCONF resource.  For instance, using the "/api/restconf"
   path discovered above, the client can now determine the version of
   RESTCONF protocol as follows:

       Request
       -------
       GET /api/restconf/version  HTTP/1.1
       Host: example.com
       Accept: application/yang.api+json

       Response
       --------
       HTTP/1.1 200 OK
       Date: Mon, 23 Apr 2012 17:01:00 GMT
       Server: example-server
       Cache-Control: no-cache
       Pragma: no-cache
       Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
       Content-Type: application/yang.api+json

       { "version": "1.0" }

===== STOP =====

From: Benoit Claise <[email-masked]<mailto:[email-masked]>>
Date: Thursday, May 15, 2014 at 12:16 AM
To: Andy Bierman <[email-masked]<mailto:[email-masked]>>, Kent Watsen <[email-masked]<mailto:[email-masked]>>
Cc: NetConf <[email-masked]<mailto:[email-masked]>>, 'Barry Leiba' <[email-masked]<mailto:[email-masked]>>, Mark Nottingham <[email-masked]<mailto:[email-masked]>>
Subject: Re: [Netconf] RESTCONF and draft-ietf-appsawg-uri-get-off-my-lawn-04 (on the IESG telechat this week)

Dear all,

Discussing this issue with Barry:
Yes, .well-known is a possible solution for netconf/restconf.  Another possibility is URI templates.  The get-off-my-lawn document talks about both.  For restconf, Mark Nottingham could help advise which would be a better option for them.
Regards, Benoit

On Tue, May 13, 2014 at 11:53 AM, Kent Watsen <[email-masked]<mailto:[email-masked]>> wrote:

Andy writes:
I think RESTCONF violates sec 2.3 wrt/ structure within the URI path.
<snip/>

I agree with Andy that RESTCONF violates section 2.3.  I also think that we can remove that violation by supporting "well-known" URIs.  Notice that the 2nd paragraph in section 2.3 says "The only exception to this requirement is registered 'well-known' URIs, as specified by [RFC5785]."   My reading is, if we use a "well-known" URI, then our subtree can defined sub-structure per RESTCONF convention.

We discussed using well-known URIs before.   Appendix B.3. in the RESTCONF draft ("Open Issues") regards ".well-known usage".  This issue was closed with the resolution "not needed in RESTCONF".   We may need to revisit that decision now.

I agree we need to support .well-known to conform to this BCP.

Thanks,
Kent

Andy

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 28 Jul 2014 11:03:00 +1000

Hi Kent,

This looks good. In a perfect world, the structure of URIs "under" the restconf resource also would be dynamic, but this is good enough for get-off-my-lawn purposes.

Cheers,

On 23 Jul 2014, at 3:42 am, Kent Watsen <[email-masked]> wrote:

> From: Kent Watsen <[email-masked]>
> To: Benoit Claise <[email-masked]>, Andy Bierman <[email-masked]>
> Cc: Mark Nottingham <[email-masked]>, 'Barry Leiba' <[email-masked]>, NetConf <[email-masked]>
> From: Benoit Claise <[email-masked]>
> To: Andy Bierman <[email-masked]>, Kent Watsen <[email-masked]>
> Cc: NetConf <[email-masked]>, 'Barry Leiba' <[email-masked]>, Mark Nottingham <[email-masked]>
>> On Tue, May 13, 2014 at 11:53 AM, Kent Watsen <[email-masked]> wrote:
>>> 
>>> Andy writes:

--
Mark Nottingham   https://www.mnot.net/