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

[Kent Watsen <[e-mail]>]

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 <[e-mail]<mailto:[e-mail]>>
Date: Thursday, May 15, 2014 at 11:21 AM
To: Benoit Claise <[e-mail]<mailto:[e-mail]>>, Andy Bierman <[e-mail]<mailto:[e-mail]>>
Cc: Mark Nottingham <[e-mail]<mailto:[e-mail]>>, 'Barry Leiba' <[e-mail]<mailto:[e-mail]>>, NetConf <[e-mail]<mailto:[e-mail]>>
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 <[e-mail]<mailto:[e-mail]>>
Date: Thursday, May 15, 2014 at 12:16 AM
To: Andy Bierman <[e-mail]<mailto:[e-mail]>>, Kent Watsen <[e-mail]<mailto:[e-mail]>>
Cc: NetConf <[e-mail]<mailto:[e-mail]>>, 'Barry Leiba' <[e-mail]<mailto:[e-mail]>>, Mark Nottingham <[e-mail]<mailto:[e-mail]>>
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 <[e-mail]<mailto:[e-mail]>> 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