Re: [Netconf] IETF Last Call Gen-ART review of draft-ietf-netconf-restconf-15
Andy Bierman <andy@yumaworks.com> Sat, 24 September 2016 16:29 UTC
Return-Path: <andy@yumaworks.com>
X-Original-To: netconf@ietfa.amsl.com
Delivered-To: netconf@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id BB599127076 for <netconf@ietfa.amsl.com>; Sat, 24 Sep 2016 09:29:00 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.6
X-Spam-Level:
X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=yumaworks-com.20150623.gappssmtp.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id KbgFR6ObNUhX for <netconf@ietfa.amsl.com>; Sat, 24 Sep 2016 09:28:57 -0700 (PDT)
Received: from mail-wm0-x22a.google.com (mail-wm0-x22a.google.com [IPv6:2a00:1450:400c:c09::22a]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 491AE127071 for <netconf@ietf.org>; Sat, 24 Sep 2016 09:28:57 -0700 (PDT)
Received: by mail-wm0-x22a.google.com with SMTP id b130so79100894wmc.0 for <netconf@ietf.org>; Sat, 24 Sep 2016 09:28:57 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yumaworks-com.20150623.gappssmtp.com; s=20150623; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=wnlxBnnEL4Dy2SNxdaY9GfjGzMkdW96jE3GOmG4qDSc=; b=NzMpEiKWSf9QajQPH1I4QqVCF9VkVY6E2ihIh8syhcPA8VpYFUGKloOYIWPBZt+tVv iU4Z3FTNA7AMrhGQIhA63yovg1lMyXUCvnlKw5LWLr+hbs9Pbc8H3hQSdWFsFs5VYkja Jj2/6K5ZIAC6zLdHsZmgNj5HcNdHp2BLN86qrUKetmFrkpeTgePNmw9xsDp9HN964jWV nH8qcSm3n3GIDyIbjHxoEfgTdh+RE7qoNC1+qOe9qxGbaqZaLvy7s+IjN8svxkr61vbp LePh58/b9YQ/ElkayVSIUK/OK/d+vOAng4zRe8DDX8RnIiAl978iP8qMx7sbl/z2Wa3+ 3yXQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=wnlxBnnEL4Dy2SNxdaY9GfjGzMkdW96jE3GOmG4qDSc=; b=Cd+lp0LMhsuvnS66UIyYtylGVOtclUfnUDyOhpNN8lHrK0j1qHu4TkNUdqORBjJh7U QvqcPw7qy2tQITif/yBXotYVwHgDU4SgfupI+Pi2+pncWYzhGHVvbNxd4Aun97SBhoX5 mS/qOhvtsVM6XqHI+EqUq7MgF9s1V54JSrEnZkll1YJ39isb4DoKV+fIzbW+lr/rkWFO OGdytEUDfYHCm3/td2tEff2q17eCdsVwUe693Qu5fSSLRXSTFVFyLJ75hHvU0fn6YYXm XGWB/MAAxjjEUcF4QrjfXRB/7ARksXRIuuGob6v9mCXPLDi22GQ8QnoZTRqoYwNBmrHK z1Dg==
X-Gm-Message-State: AE9vXwPok3UeXH2OpDf7uT7ziVBpAWmjZFOcZQaKQ7LRWOI7xWqB0e52ZJLKl70QEQ5VFaaSY1vRJDvGiJJEZw==
X-Received: by 10.194.170.163 with SMTP id an3mr13125269wjc.73.1474734535683; Sat, 24 Sep 2016 09:28:55 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.80.141.78 with HTTP; Sat, 24 Sep 2016 09:28:54 -0700 (PDT)
In-Reply-To: <87zinbq4ai.fsf@hobgoblin.ariadne.com>
References: <87zinbq4ai.fsf@hobgoblin.ariadne.com>
From: Andy Bierman <andy@yumaworks.com>
Date: Sat, 24 Sep 2016 09:28:54 -0700
Message-ID: <CABCOCHTmxNNrGopELX=w+XvG2Q=NoxrxEzJ0OzJ3o2yyxTDCLA@mail.gmail.com>
To: "Dale R. Worley" <worley@ariadne.com>
Content-Type: multipart/alternative; boundary="089e0122f07c23495a053d436427"
Archived-At: <https://mailarchive.ietf.org/arch/msg/netconf/lTgVoB67iVTiHI5SA7XKG2Osm6A>
Cc: Netconf <netconf@ietf.org>
Subject: Re: [Netconf] IETF Last Call Gen-ART review of draft-ietf-netconf-restconf-15
X-BeenThere: netconf@ietf.org
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: Network Configuration WG mailing list <netconf.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netconf>, <mailto:netconf-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netconf/>
List-Post: <mailto:netconf@ietf.org>
List-Help: <mailto:netconf-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netconf>, <mailto:netconf-request@ietf.org?subject=subscribe>
X-List-Received-Date: Sat, 24 Sep 2016 16:29:01 -0000
On Tue, Sep 13, 2016 at 7:10 AM, Dale R. Worley <worley@ariadne.com> wrote: > This is a comparison of draft-ietf-netconf-restconf-16 against my > review for draft-ietf-netconf-restconf-15. I've removed items that > have been (IMO) completely resolved. > > * Technical nits > > - In a few places, returned data can include URIs that are intended to > be usable by the client to retrieve information from the Restconf > server. These places include the <location> element for accessing an > event stream, the Location header of POST responses, and the URLs for > retrieving schema resources (section 3.7). The problem > is that implementing this assumes that the server knows a host > identifier (domain name or address) that the client can use to access > the server. In general, given the ubiquity of NATs, the server > doesn't know this. > > It seems to me that the two possible solutions are for the server to > be able to return a URI *relative reference* or for the server to use > as the host-part of the URL the value in the Host header of the > request (which perforce the server knows the client can use to access > the server). Perhaps this is a known problem with a known solution > and so the draft doesn't bother to mention it. Then again, perhaps in > practice the clients and the server are in region of the network > containing no internal NATS, and the problem does not arise. > > But it seems to me that this could be a very general problem for > implementers and they should be instructed how to deal with it. I > suspect that the authors know the intended resolution of this issue, > but it would help if the resolution was stated explicitly. > > There seems to be no discussion of this issue. > > The WG has not agreed that the server does not know what to put in the Location header. no edit made > - Does XRD (RFC 6415) admit relative links as values of the href > attribute of the Link element? Relative links are not usually > considered to be "URIs", but rather "URI-references" (RFC 3986 section > 4.1), and RFC 6415 uses "URI" consistently, not "URI-reference". > Also, all examples in RFC 6415 show complete URIs. If the href > attributes have to be full URIs, then the problem with host > identifiers described above also arises. > > This issue doesn't seem to have been addressed at all in the draft, > though I have a vague memory of discussion of using templates as an > alternative. But all of the XRD examples seem to be incorrect in that > they use relative URIs as values of the href attribute. > I asked Kent and Martin to research this issue > > * General issues > > - Might it be useful to consistently use a trailing-backslash > convention? > > This is largely done, but there are some additional places where it is > needed: > > In the example in section 6.2, there are several places where > "</locaton>" appears on a line of its own. It appears that the > preceding line was intended to end with "/". > > In the example in section 6.3, this XML appears to be missing "/": > > fixed > - There seem to be six statements in the draft that the fragment field > in RESTCONF resource URIs has no defined purpose, either for some set > of resources or for all resources. (sections 3.4, 3.5, 3.6, 3.8, 5.1 > (twice) But of course, the fragment identifier is never presented to > the HTTP/HTTPS server for the resource -- see RFC 7230 section 5.1: > > The target URI excludes the reference's fragment component, if any, > since fragment identifiers are reserved for client-side processing > ([RFC3986], Section 3.5). > > There are still several statements like "The fragment field in the > request URI has no defined purpose if the target resource is a > datastore resource." These statements remain meaningless, since by > the specification of HTTP, the fragment identifier is *never* included > in a request URI. > > The most you can say is, e.g., that the resource returned by fetching > a datastore resource is never of a media type for which fragment > identifiers are defined. But that requires checking that datastore > resources can never return such types, either now or in the future. > > these sentences have been removed > * Nits > > 1.1.5. Terms > > The term "operation" is used in at least three senses: > > - HTTP request methods (e.g., the title of section 4) > ... > > > Perhaps section 4 could be better titled "RESTCONF Methods", since the > subsections are labeled with HTTP method names? > changed title of sec. 4 > > 3.5.3. Encoding Data Resource Identifiers in the Request URI > > Note that double-quote is not a reserved > characters and does not need to be percent-encoded. > > s/characters/character/ > fixed > > 3.5.3.1. ABNF For Data Resource Identifiers > > api-path = "/" | > ("/" api-identifier > 0*("/" (api-identifier | list-instance ))) > > The new ABNF is much better! However, there is one point that's not > clear to me: > > string = <a quoted or unquoted string> > > changed to string = <an unquoted string> > This suggests to me that in a path component identifying a list > instance, one can write the quoted string ".../node="key-value"/...". > But I'm sure that's not intended, as there is no mention of quoting > elsewhere in the text. I suspect that omitting this definition and > leaving > > key-value = string ;; constrained chars are percent-encoded > > would have the intended meaning. > > 4.8.3. The "fields" Query Parameter > > The server does not return a set separate sub-resources. > > I think that the word "of" has been omitted from this sentence. > > fixed > 6.3. Subscribing to Receive Notifications > > <location > xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> > https://example.com/streams/NETCONF > </location> > > Shouldn't there be backslashes here? > > fixed > 8. RESTCONF module > > The following data-def-stmt sub-statements have special > meaning when used within a yang-data-resource extension > statement. > - The list-stmt is not required to have a key-stmt defined. > - The if-feature-stmt is ignored if present. > - The config-stmt is ignored if present. > - The available identity values for any 'identityref' > leaf or leaf-list nodes is limited to the module > containing this extension statement, and the modules > imported into that module. > > It seems like poor practice to have the extension be described as > changing the semantics of Yang. Better would be to turn these into > constraints, so that the valid contents of yang-data are a subset of > Yang, but that subset has the same semantics as Yang prescribes: > > - The if-feature-stmt must not be present. > - If the config-stmt is present, its value must be 'false'. > - The available identity values for any 'identityref' > leaf or leaf-list nodes is limited to the module > containing this extension statement, and the modules > imported into that module. [unchanged!] > > The item "The list-stmt is not required to have a key-stmt defined." > is redundant, since everything inside yang-data is not configuration > data, and non-configuration lists need not have keys. > > None of these (IMO) improvements have been done. > > The suggested edits are not accepted. They prevent groupings from being used within a YANG data template. > 9. RESTCONF Monitoring > > The nodes 'description' and 'replay-support' are shown as optional in > the tree diagram: > > +--ro restconf-state > +--ro streams > +--ro stream* [name] > +--ro description? string > +--ro replay-support? boolean > +--ro replay-log-creation-time? yang:date-and-time > > but there is no 'mandatory "false";' for leaf "description" in > section 9.3. Or should it have a default value? (There is a > default value for leaf reply-support, so it is sort-of optional.) > > The '?' is correct. The default for the YANG mandatory-stmt is false. The "description" and "replay-support" nodes do not exist unless set by the client. A YANG default is the value that will be used if no instance exists. > leaf description { > type string; > description "Description of stream content"; > reference > "RFC 5277, Section 3.4, <description> element."; > } > > 11.3.1. Media Type application/yang-data-xml > > Fragment identifier considerations: The fragment field in the > request URI has no defined purpose. > > This needs to be rephrased. By the definition of HTTP, the fragment > field is *never* included in a request URI. What you mean to say is > something like "Fragment identifiers for this type are not defined.". > > fixed > D.2.3. Edit a Datastore Resource > > "album" sub-resource to eachof 2 "artist" resources: > > s/eachof/each of/ > > fixed > Dale > Andy > > _______________________________________________ > Netconf mailing list > Netconf@ietf.org > https://www.ietf.org/mailman/listinfo/netconf >
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Andy Bierman
- [Netconf] IETF Last Call Gen-ART review of draft-… Dale R. Worley
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Dale R. Worley
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Andy Bierman
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Andy Bierman
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Martin Bjorklund
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Dale R. Worley
- Re: [Netconf] IETF Last Call Gen-ART review of dr… Dale R. Worley