Subject: Re: [Netconf] I-D Action: draft-ietf-netconf-restconf-03.txt

From: Jonathan Hansford <[email-masked]>
Date: Fri, 14 Nov 2014 13:18:03 +0000

Hi, 

Section 1.2 

 	* The section is entitled "Simple Subset of
NETCONF Functionality", but if the only aspects of NETCONF it is lacking
are the transaction features bulleted in the third paragraph then the
title seems to be underselling it somewhat.
 	* I'm a little confused
with the first paragraph; maybe it is just the way I am reading it. The
first sentence appears to describe what RESTCONF needs to be, whereas
the second appears to describe what RESTCONF lacks (based on the third
paragraph). However, both sentences (and the second paragraph) talk
about what is or is not "needed". Could these be reworded to clarify
what RESTCONF provides and what it doesn't?
 	* Is there any intent to
address these additional needs at some point, or is it assumed RESTCONF
is adequate without them? Is there any reason why they aren't being
addressed at this time?
 	* The transaction features listed in the third
paragraph are all capabilities defined in RFC 6241 plus RFC 5717. Are
all other capabilities from 6241 (i.e. those not listed in this
paragraph) supported by RESTCONF (e.g. Rollback-on-Error)?

Thanks,

Jonathan 

On 2014-10-25 23:16, Andy Bierman wrote: 

> FYI,
> This
version of RESTCONF addresses all issues on the github tracker
> except
maybe #9. Also, #11 was deferred to a future release.
> A change was
made to the "stream" list in ietf-restconf-monitoring.yang
> to allow
separate stream links for XML and (optionally) JSON encoding
> of
notifications.
> 
> A "collection" resource, plus "limit" and "offset"
query parameters,
> have been added to allow multiple leaf-list and list
instances
> to be retrieved. The optional "page" capability allows
pagination of
> list entries, using the limit and offset parameters.
>

> Issue List:
> https://github.com/netconf-wg/restconf/issues
> 
>
Please review the draft and send any comments to the mailing list.
Please post any objections to closing the issues #2 - #8 and #10 -
#13.
> 
> thanks,
> Andy
> 
> On Sat, Oct 25, 2014 at 3:46 PM,
<[email-masked]> wrote:
>> A New Internet-Draft is
available from the on-line Internet-Drafts directories. This draft is a
work item of the Network Configuration Working Group of the IETF. Title
: RESTCONF Protocol Authors : Andy Bierman Martin Bjorklund Kent Watsen
Filename : draft-ietf-netconf-restconf-03.txt Pages : 99 Date :
2014-10-25 Abstract: This document describes an HTTP-based protocol that
provides a programmatic interface for accessing data defined in YANG,
using the datastores defined in NETCONF. The IETF datatracker status
page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-netconf-restconf/ [1]
There's also a htmlized version available at:
http://tools.ietf.org/html/draft-ietf-netconf-restconf-03 [2] A diff
from the previous version is available at:
http://www.ietf.org/rfcdiff?url2=draft-ietf-netconf-restconf-03 [3]
Please note that it may take a couple of minutes from the time of
submission until the htmlized version and diff are available at
tools.ietf.org. Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/ [4]
_______________________________________________ I-D-Announce mailing
list [email-masked] [5]
https://www.ietf.org/mailman/listinfo/i-d-announce [6] Internet-Draft
directories: http://www.ietf.org/shadow.html [7] or
ftp://ftp.ietf.org/ietf/1shadow-sites.txt [8]
_______________________________________________
> Netconf mailing list
[email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

Links:
------
[1]
https://datatracker.ietf.org/doc/draft-ietf-netconf-restconf/
[2]
http://tools.ietf.org/html/draft-ietf-netconf-restconf-03
[3]
http://www.ietf.org/rfcdiff?url2=draft-ietf-netconf-restconf-03
[4]
http://webmail.plus.net/ftp://ftp.ietf.org/internet-drafts/
[5]
mailto:[email-masked]
[6]
https://www.ietf.org/mailman/listinfo/i-d-announce
[7]
http://www.ietf.org/shadow.html
[8]
http://webmail.plus.net/ftp://ftp.ietf.org/ietf/1shadow-sites.txt

---

From: "Jonathan Hansford" <[email-masked]>
Date: Fri, 14 Nov 2014 16:29:06 -0000

Hi,

I've never worked with HTTP and so have been following up the HTTP
definitions listed in section 1.4.2:

*         The terms 'fragment' and 'query' are actually defined in RFC 3986

*         The term 'header line' is not defined in RFC 2616. Are you using
it as a generic term for 'request line' and 'status line' that are defined
in that RFC?

*         The term 'path' is not defined in RFC 2616 and is used in that RFC
for a number of purposes. I presume it is the URI 'path' that is intended,
which is defined in RFC 3986

*         The term 'response body' is not defined in RFC 2616 but I presume
it means the message body of the response.

Jonathan

-----Original Message-----
From: Netconf [mailto:[email-masked]] On Behalf Of Andy Bierman
Sent: 26 October 2014 00:17
Cc: Netconf
Subject: Re: [Netconf] I-D Action: draft-ietf-netconf-restconf-03.txt

FYI,

This version of RESTCONF addresses all issues on the github tracker except
maybe #9. Also,  #11 was deferred to a future release.

A change was made to the "stream" list in ietf-restconf-monitoring.yang to
allow separate stream links for XML and (optionally) JSON encoding of
notifications.

A "collection" resource, plus "limit" and "offset" query parameters, have
been added to allow multiple leaf-list and list instances to be retrieved.
The optional "page" capability allows pagination of list entries, using the
limit and offset parameters.

Issue List:

 <https://github.com/netconf-wg/restconf/issues>
https://github.com/netconf-wg/restconf/issues

Please post any objections to closing the issues #2 - #8 and #10 - #13.

thanks,

Andy

On Sat, Oct 25, 2014 at 3:46 PM,  < <mailto:[email-masked]>
[email-masked]> wrote:

> A New Internet-Draft is available from the on-line Internet-Drafts
directories.

>  This draft is a work item of the Network Configuration Working Group of
the IETF.

>         Title           : RESTCONF Protocol

>         Authors         : Andy Bierman

>                           Martin Bjorklund

>                           Kent Watsen

>         Filename        : draft-ietf-netconf-restconf-03.txt

>         Pages           : 99

>         Date            : 2014-10-25

> Abstract:

>    This document describes an HTTP-based protocol that provides a

>    programmatic interface for accessing data defined in YANG, using the

>    datastores defined in NETCONF.

> The IETF datatracker status page for this draft is:

>  <https://datatracker.ietf.org/doc/draft-ietf-netconf-restconf/>

>  <http://tools.ietf.org/html/draft-ietf-netconf-restconf-03>

> A diff from the previous version is available at:

>  <http://www.ietf.org/rfcdiff?url2=draft-ietf-netconf-restconf-03>

> submission until the htmlized version and diff are available at
tools.ietf.org.

> Internet-Drafts are also available by anonymous FTP at:

>  <ftp://ftp.ietf.org/internet-drafts/> ftp://ftp.ietf.org/internet-drafts/

> I-D-Announce mailing list

>  <mailto:[email-masked]> [email-masked]

>  <https://www.ietf.org/mailman/listinfo/i-d-announce>

> Internet-Draft directories:  <http://www.ietf.org/shadow.html>
http://www.ietf.org/shadow.html or 

>  <ftp://ftp.ietf.org/ietf/1shadow-sites.txt>
ftp://ftp.ietf.org/ietf/1shadow-sites.txt

Netconf mailing list

 <mailto:[email-masked]> [email-masked]

 <https://www.ietf.org/mailman/listinfo/netconf>
https://www.ietf.org/mailman/listinfo/netconf

---

From: "Jonathan Hansford" <[email-masked]>
Date: Fri, 14 Nov 2014 17:44:22 -0000

Also, RFC2616 was obsoleted in June 2014 by RFC 7230, RFC 7231, RFC 7232,
RFC 7233, RFC 7234 and RFC 7235, so should they be referenced instead?

*         RFC 3986

o   Fragment

o   Path

o   Query

*         RFC 7230

o   Message body

o   Header line (request line and status line?)

o   Request URI (the reference appears to be generally to the 'effective
request URI')

o   Response body (actually the 'message body' of the response)

*         RFC 7231 

o   Method

o   Request (doesn't appear to be formally defined anywhere)

o   Resource

*         RFC 7232

o   Entity tag

From: Netconf [mailto:[email-masked]] On Behalf Of Jonathan
Hansford
Sent: 14 November 2014 16:29
To: 'Andy Bierman'
Cc: 'Netconf'
Subject: Re: [Netconf] I-D Action: draft-ietf-netconf-restconf-03.txt

Hi,

Jonathan

-----Original Message-----
From: Netconf [mailto:[email-masked]] On Behalf Of Andy Bierman
Sent: 26 October 2014 00:17
Cc: Netconf
Subject: Re: [Netconf] I-D Action: draft-ietf-netconf-restconf-03.txt

FYI,

Issue List:

 

thanks,

Andy

On Sat, Oct 25, 2014 at 3:46 PM,  < <mailto:[email-masked]>
[email-masked]> wrote:

directories.

the IETF.

tools.ietf.org.

Netconf mailing list

---

From: "Jonathan Hansford" <[email-masked]>
Date: Wed, 19 Nov 2014 09:24:02 -0000

Hi,

Having read further, I am really confused about what section 1.2 is telling me about the transaction features not directly provided by RESTCONF.

Datastore locking: this is identified as not directly provided, yet section 6.1 appears to show a lock attempt on a datastore.

Candidate and startup datastores: again not directly provided, yet section 1.2 states a “simplified framework and protocol is needed that utilizes the three NETCONF datastores (candidate, running, startup)”. Section 1.4.4 states:

unified datastore: A conceptual representation of the device running configuration.  The server will hide all NETCONF datastore details for edit operations, such as the ":candidate" and ":startup" capabilities.

which seems to indicate the unified datastore is a representation of just the running configuration. However, section 2.4 states:

The underlying NETCONF datastores (i.e., candidate, running, startup) can be used to implement the unified datastore, but the server design is not limited to the exact datastore procedures defined in NETCONF.

The "candidate" and "startup" datastores are not visible in the RESTCONF protocol.  Transaction management and configuration persistence are handled by the server and not controlled by the client.

So, can the “candidate” and “startup” datastores be used to implement the unified datastore or not? 

If so, what impact does that have on RESTCONF and how can the client access them using RESTCONF? 

Or is it just that a server supporting both NETCONF and RESTCONF may support both :candidate and :startup just for NETCONF clients? 

And how is transaction management and configuration persistence handled by the server, or is that again through NETCONF but not through RESTCONF?

Is RESTCONF providing the “simplified framework and protocol … that utilizes the three NETCONF datastores (candidate, running, startup)” and, if not, why say it in this document?

Thanks,

Jonathan

From: Netconf [mailto:[email-masked]] On Behalf Of Jonathan Hansford
Sent: 14 November 2014 13:18
To: [email-masked]
Subject: Re: [Netconf] I-D Action: draft-ietf-netconf-restconf-03.txt

Hi,

Section 1.2

*	The section is entitled "Simple Subset of NETCONF Functionality", but if the only aspects of NETCONF it is lacking are the transaction features bulleted in the third paragraph then the title seems to be underselling it somewhat.
*	I'm a little confused with the first paragraph; maybe it is just the way I am reading it. The first sentence appears to describe what RESTCONF needs to be, whereas the second appears to describe what RESTCONF lacks (based on the third paragraph). However, both sentences (and the second paragraph) talk about what is or is not "needed". Could these be reworded to clarify what RESTCONF provides and what it doesn't?
*	Is there any intent to address these additional needs at some point, or is it assumed RESTCONF is adequate without them? Is there any reason why they aren't being addressed at this time?
*	The transaction features listed in the third paragraph are all capabilities defined in RFC 6241 plus RFC 5717. Are all other capabilities from 6241 (i.e. those not listed in this paragraph) supported by RESTCONF (e.g. Rollback-on-Error)?

Thanks,

Jonathan

FYI,
 
This version of RESTCONF addresses all issues on the github tracker
except maybe #9. Also,  #11 was deferred to a future release.
 
A change was made to the "stream" list in ietf-restconf-monitoring.yang
to allow separate stream links for XML and (optionally) JSON encoding
of notifications.
 
A "collection" resource, plus "limit" and "offset" query parameters,
have been added to allow multiple leaf-list and list instances
to be retrieved. The optional "page" capability allows pagination of
list entries, using the limit and offset parameters.
 
Issue List:

thanks,
Andy
 
On Sat, Oct 25, 2014 at 3:46 PM,  <[email-masked] <mailto:[email-masked]> > wrote:

A New Internet-Draft is available from the on-line Internet-Drafts directories. This draft is a work item of the Network Configuration Working Group of the IETF. Title : RESTCONF Protocol Authors : Andy Bierman Martin Bjorklund Kent Watsen Filename : draft-ietf-netconf-restconf-03.txt Pages : 99 Date : 2014-10-25 Abstract: This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF. The IETF datatracker status page for this draft is: https://datatracker.ietf.org/doc/draft-ietf-netconf-restconf/ There's also a htmlized version available at: http://tools.ietf.org/html/draft-ietf-netconf-restconf-03 A diff from the previous version is available at: http://www.ietf.org/rfcdiff?url2=draft-ietf-netconf-restconf-03 Please note that it may take a couple of minutes from the time of submission until the htmlized version and diff are available at tools.ietf.org. Internet-Drafts are also available by anonymous FTP at: ftp://ftp.ietf.org/internet-drafts/ _______________________________________________ I-D-Announce mailing list [email-masked] <mailto:[email-masked]>  https://www.ietf.org/mailman/listinfo/i-d-announce Internet-Draft directories: http://www.ietf.org/shadow.html or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

_______________________________________________
Netconf mailing list
[email-masked] <mailto:[email-masked]> 
https://www.ietf.org/mailman/listinfo/netconf

---

From: Andy Bierman <[email-masked]>
Date: Thu, 20 Nov 2014 16:14:53 -0800

Hi,

We are updating the draft based on this email and previous 2 emails.

thanks,
Andy

On Fri, Nov 14, 2014 at 9:44 AM, Jonathan Hansford
<[email-masked]> wrote:
> ·         RFC 3986
> ·         RFC 7230
> o   Request URI (the reference appears to be generally to the ‘effective
> request URI’)
>
> o   Response body (actually the ‘message body’ of the response)
>
> ·         RFC 7231
>
> o   Method
>
> o   Request (doesn’t appear to be formally defined anywhere)
>
> o   Resource
>
> ·         RFC 7232
>
> o   Entity tag
>
>
>
>
>
> I’ve never worked with HTTP and so have been following up the HTTP
> ·         The terms ‘fragment’ and ‘query’ are actually defined in RFC 3986
>
> ·         The term ‘header line’ is not defined in RFC 2616. Are you using
> it as a generic term for ‘request line’ and ‘status line’ that are defined
> in that RFC?
>
> ·         The term ‘path’ is not defined in RFC 2616 and is used in that RFC
> for a number of purposes. I presume it is the URI ‘path’ that is intended,
> ·         The term ‘response body’ is not defined in RFC 2616 but I presume
> On Sat, Oct 25, 2014 at 3:46 PM,  <[email-masked]> wrote:
>
>>
>
>> ftp://ftp.ietf.org/internet-drafts/
>
>>
>
>> [email-masked]
>> Internet-Draft directories: http://www.ietf.org/shadow.html or
>

---

From: Andy Bierman <[email-masked]>
Date: Thu, 20 Nov 2014 16:28:27 -0800

On Wed, Nov 19, 2014 at 1:24 AM, Jonathan Hansford
<[email-masked]> wrote:
> Hi,
>
>
>
> Having read further, I am really confused about what section 1.2 is telling
> me about the transaction features not directly provided by RESTCONF.
>
>
>
> Datastore locking: this is identified as not directly provided, yet section
> 6.1 appears to show a lock attempt on a datastore.
>

that is a bad example -- we will change it.

>
>
> Candidate and startup datastores: again not directly provided, yet section
> 1.2 states a “simplified framework and protocol is needed that utilizes the
> three NETCONF datastores (candidate, running, startup)”. Section 1.4.4
> states:
>
>

I think the term "utilizes" is wrong.
It should be "co-exists".

>
> unified datastore: A conceptual representation of the device running
> configuration.  The server will hide all NETCONF datastore details for edit
> operations, such as the ":candidate" and ":startup" capabilities.
>
>

It is an implementation detail how the complete an edit
within the unified datastore in RESTCONF.

>
> which seems to indicate the unified datastore is a representation of just
> the running configuration. However, section 2.4 states:
>
>
>
> The underlying NETCONF datastores (i.e., candidate, running, startup) can be
> used to implement the unified datastore, but the server design is not
> limited to the exact datastore procedures defined in NETCONF.
>

correct -- the unified datastore may act like distinct-startup,
but is not required to be implemented in any specific manner.
The results of the operation requests are what matter.

>
>
> The "candidate" and "startup" datastores are not visible in the RESTCONF
> protocol.  Transaction management and configuration persistence are handled
> by the server and not controlled by the client.
>
>
>

It is an implementation detail. The external datastores named
candidate and startup are not present in RESTCONF.
If you mean can you use your internal implementations, then yes.

An edit is expected to persist right away in RESTCONF
even if the :startup capability is supported in NETCONF.

> If so, what impact does that have on RESTCONF and how can the client access

Try /restconf/operations/edit-config

>
>
> Or is it just that a server supporting both NETCONF and RESTCONF may support
> both :candidate and :startup just for NETCONF clients?
>
>
>
> And how is transaction management and configuration persistence handled by
> the server, or is that again through NETCONF but not through RESTCONF?
>

An edit is expected to persist right away

Use /restconf/operations/<netconf> if you want to use NETCONF over HTTP.
It is not a priority of RESTCONF to provide a state-full complex protocol like
NETCONF.   Sec. 1.2 points out that you should use NETCONF if you need
the features that RESTCONF does not provide,.

>
>
> Is RESTCONF providing the “simplified framework and protocol … that utilizes
> the three NETCONF datastores (candidate, running, startup)” and, if not, why
> say it in this document?
>

We will change the word "utilizes" to "co-exists with"

Andy

> The section is entitled "Simple Subset of NETCONF Functionality", but if the
> only aspects of NETCONF it is lacking are the transaction features bulleted
> in the third paragraph then the title seems to be underselling it somewhat.
> I'm a little confused with the first paragraph; maybe it is just the way I
> am reading it. The first sentence appears to describe what RESTCONF needs to
> be, whereas the second appears to describe what RESTCONF lacks (based on the
> third paragraph). However, both sentences (and the second paragraph) talk
> about what is or is not "needed". Could these be reworded to clarify what
> RESTCONF provides and what it doesn't?
> Is there any intent to address these additional needs at some point, or is
> it assumed RESTCONF is adequate without them? Is there any reason why they
> aren't being addressed at this time?
> The transaction features listed in the third paragraph are all capabilities
> defined in RFC 6241 plus RFC 5717. Are all other capabilities from 6241
> (i.e. those not listed in this paragraph) supported by RESTCONF (e.g.
> Rollback-on-Error)?
>
> Thanks,
>
> Jonathan
>
> directories. This draft is a work item of the Network Configuration Working
> Group of the IETF. Title : RESTCONF Protocol Authors : Andy Bierman Martin
> Bjorklund Kent Watsen Filename : draft-ietf-netconf-restconf-03.txt Pages :
> 99 Date : 2014-10-25 Abstract: This document describes an HTTP-based
> protocol that provides a programmatic interface for accessing data defined
> in YANG, using the datastores defined in NETCONF. The IETF datatracker
> status page for this draft is:
> https://datatracker.ietf.org/doc/draft-ietf-netconf-restconf/ There's also a
> htmlized version available at:
> http://tools.ietf.org/html/draft-ietf-netconf-restconf-03 A diff from the
> previous version is available at:
> http://www.ietf.org/rfcdiff?url2=draft-ietf-netconf-restconf-03 Please note
> that it may take a couple of minutes from the time of submission until the
> htmlized version and diff are available at tools.ietf.org. Internet-Drafts
> are also available by anonymous FTP at: ftp://ftp.ietf.org/internet-drafts/
> _______________________________________________ I-D-Announce mailing list
> [email-masked] https://www.ietf.org/mailman/listinfo/i-d-announce