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

From: Benoit Claise <[email-masked]>
Date: Mon, 12 May 2014 15:49:16 -0700

Dear all,

Please review the 
http://tools.ietf.org/html/draft-ietf-appsawg-uri-get-off-my-lawn-04 BCP 
in light of RESTCONF and let me know.

Regards, Benoit

---

From: Andy Bierman <[email-masked]>
Date: Mon, 12 May 2014 16:06:03 -0700

On Mon, May 12, 2014 at 3:49 PM, Benoit Claise <[email-masked]> wrote:

> Dear all,
>
> Please review the http://tools.ietf.org/html/draft-ietf-appsawg-uri-get-
> off-my-lawn-04 BCP in light of RESTCONF and let me know.
>
>

I think RESTCONF violates sec 2.3 wrt/ structure within the URI path.
This is by design.  The document complains about ad-hoc mechanisms,
and RESTCONF is in complete agreement with that.  The RESTCONF
mapping of data nodes to resource identifiers is the opposite of ad-hoc.
It allows multi-vendor naming without collisions and dramatically
improved application efficiency.  (It is arguable that configuration
management
of complex routers would be impossible with a robust schema language
like YANG).

Regards, Benoit
Andy

---

From: Andy Bierman <[email-masked]>
Date: Mon, 12 May 2014 17:40:15 -0700

> of complex routers would be impossible with a robust schema language

oops -- s/with/without/ in previous line

---

From: Kent Watsen <[email-masked]>
Date: Tue, 13 May 2014 18:53:07 +0000

Andy writes:
<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.

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Tue, 13 May 2014 12:03:49 -0700

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

>  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.

Andy

---

From: Benoit Claise <[email-masked]>
Date: Wed, 14 May 2014 21:16:15 -0700

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 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.
>
>     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.
>
>

---

From: Kent Watsen <[email-masked]>
Date: Thu, 15 May 2014 15:21:42 +0000

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:

Thanks,
Kent

Andy