Subject: [Netconf] restconf-09 comments

From: Robert Wilton <[email-masked]>
Date: Fri, 4 Mar 2016 14:16:13 +0000

Hi,

I appreciate that this is a while after the last call, but when reading 
restconf-09, I had a few minor comments (which may have already been 
pointed out by others previously).

1. Regarding "4.8.1.  The "content" Query Parameter":

    The default value is determined by the "config" statement value of
    the requested data nodes.  If the "config" value is "false", then the
    default for the "content" parameter is "nonconfig".  If "config" is
    "true" then the default for the "content" parameter is "config".

I was surprised so see that the default value wasn't just "all",
  - "all" felt like a more obvious default choice, i.e. don't filter the 
result unless explicitly asked to.
  - it means the behaviour is consistent whether a GET request is made 
on the top-level datastore URI or any child node underneath the root.
  - it is easier to document/explain/understand (and possibly implement).
  - It is the same regardless for nonconfig anyway, so would only affect 
the default behaviour for config nodes anyway.

2. The "D.1.1.  Retrieve the Top-level API Resource" example looked 
slightly wrong to me.  from the  RESTCONF module definition in section 8 
I would expect the data and operations container to be empty JSON objects.

OLD:

    The server might respond as follows:

       HTTP/1.1 200 OK
       Date: Mon, 23 Apr 2012 17:01:00 GMT
       Server: example-server
       Content-Type: application/yang.api+json

       {
         "ietf-restconf:restconf": {
*"data" : [ null ], "operations" : [ null ]*
         }
       }

NEW:

    The server might respond as follows:

       HTTP/1.1 200 OK
       Date: Mon, 23 Apr 2012 17:01:00 GMT
       Server: example-server
       Content-Type: application/yang.api+json

       {
         "ietf-restconf:restconf": {
*"data" : { }, "operations" : { }*
         }
       }

3. In "D.1.3.  Retrieve The Server Capability Information", the example 
is XML rather than JSON.

OLD:

    In this example the client is retrieving the capability information
    from the server in*JSON *format, and the server supports all the
    RESTCONF query parameters, plus one vendor parameter:

NEW:
    In this example the client is retrieving the capability information
    from the server in*XML *format, and the server supports all the
    RESTCONF query parameters, plus one vendor parameter:

Rob

---

From: Andy Bierman <[email-masked]>
Date: Fri, 4 Mar 2016 07:29:45 -0800

On Fri, Mar 4, 2016 at 6:16 AM, Robert Wilton <[email-masked]> wrote:

>  - it means the behaviour is consistent whether a GET request is made on
> the top-level datastore URI or any child node underneath the root.

The default will be 'all' if the target resource is the datastore itself.

> slightly wrong to me.  from the  RESTCONF module definition in section 8 I
> would expect the data and operations container to be empty JSON objects.
>
> OLD:
>
>         "ietf-restconf:restconf": {*          "data" : [ null ],
>           "operations" : [ null ]*
>         }
>       }
>
>
> NEW:
>
>         "ietf-restconf:restconf": {*          "data" : { },
>           "operations" : { }*
>         }
>       }
>
>

I think the text says the API resource is returned which includes these
2 child nodes, also application/yang.api

>
> 3. In "D.1.3.  Retrieve The Server Capability Information", the example is
> XML rather than JSON.
>
> OLD:
>
>    from the server in *JSON *format, and the server supports all the
>    from the server in *XML *format, and the server supports all the
OK

> Rob
Andy

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

---

From: Robert Wilton <[email-masked]>
Date: Fri, 4 Mar 2016 17:10:22 +0000

Hi Andy,

On 04/03/2016 15:29, Andy Bierman wrote:
>
>
> On Fri, Mar 4, 2016 at 6:16 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     Hi,
>
>     I appreciate that this is a while after the last call, but when
>     reading restconf-09, I had a few minor comments (which may have
>     already been pointed out by others previously).
>
>      - "all" felt like a more obvious default choice, i.e. don't
>     filter the result unless explicitly asked to.
>      - it means the behaviour is consistent whether a GET request is
>     made on the top-level datastore URI or any child node underneath
>     the root.
>      - It is the same regardless for nonconfig anyway, so would only
>     affect the default behaviour for config nodes anyway.
>
>
>
Yes.  As above, that is one of the reasons why I think that it would be 
better if the default is "all" for any nodes within the datastore itself 
as well.  It makes it more consistent.

>
>
>     2. The "D.1.1.  Retrieve the Top-level API Resource" example
>     looked slightly wrong to me.  from the  RESTCONF module definition
>     in section 8 I would expect the data and operations container to
>     be empty JSON objects.
>
>     OLD:
>
Section 3.3.  API Resource states:

    The "application/yang.api" restconf-media-type extension in the
    "ietf-restconf" module defined inSection 8 
<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-8>  is used to specify the
    structure and syntax of the conceptual child resources within the API
    resource.

Section 8 gives a YANG module that has data and operations as 
containers.  I can't obviously see any text which states that these two 
containers should be represented as two leaves of type empty instead of 
a JSON interpretation of the YANG module definition.  So I still believe 
that either the textual description or the example needs to be fixed.

Thanks,
Rob

>
>
>     3. In "D.1.3.  Retrieve The Server Capability Information", the
>     example is XML rather than JSON.
>
>     OLD:
>
>     [email-masked] <mailto:[email-masked]>

---

From: Andy Bierman <[email-masked]>
Date: Fri, 4 Mar 2016 10:43:13 -0800

On Fri, Mar 4, 2016 at 9:10 AM, Robert Wilton <[email-masked]> wrote:

> better if the default is "all" for any nodes within the datastore itself as
> well.  It makes it more consistent.
>
>
>

Is there is WG consensus to make this change?
What do others think?

OLD:  (text cited above in 4.8.1)

NEW: The default value is 'all'.

This means that in order to do a "get-config" the content=config parameter
always has to be used.
The current solution is optimized for configuration data nodes.

>    "ietf-restconf" module defined in Section 8 <https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-8> is used to specify the
> Section 8 gives a YANG module that has data and operations as containers.
> I can't obviously see any text which states that these two containers
> should be represented as two leaves of type empty instead of a JSON
> interpretation of the YANG module definition.  So I still believe that
> either the textual description or the example needs to be fixed.
>
>

OK -- I will try to fix the module definition

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 08 Mar 2016 15:37:14 +0100 (CET)

> The current solution is optimized for configuration data nodes.

I think I agree with Rob that it would be more consistent to use 'all'
as the default value.  If we wanted to optimize for config, we should
probably have used 'config' as the default also for the datastore
resource.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 8 Mar 2016 08:18:16 -0800

On Tue, Mar 8, 2016 at 6:37 AM, Martin Bjorklund <[email-masked]> wrote:

> reading
> on
> affect
OK with me -- this solves the problem where "fields" contains nonconfig
nodes.

Andy

> > >    "ietf-restconf" module defined in Section 8 <
> https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-8> is
> used to specify the
> containers.

---

From: Andy Bierman <[email-masked]>
Date: Wed, 9 Mar 2016 14:38:35 -0800

> the default behaviour for config nodes anyway.
Added issue 53, now in edit state (changed default to "all")

https://github.com/netconf-wg/restconf/issues/53

>         "ietf-restconf:restconf": {*          "data" : { },
Added new issue 54, still open; need to check the JSON draft
https://github.com/netconf-wg/restconf/issues/54

>    RESTCONF query parameters, plus one vendor parameter:

Fixed

Andy

---

From: Robert Wilton <[email-masked]>
Date: Thu, 10 Mar 2016 10:03:45 +0000

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

 From my reading of the JSON encoding rules:
The "OLD" example is effectively representing data and operations as 
leaves of type empty.
The "NEW" example is representing them as empty containers.

I have no preference over which is more appropriate, just that the 
specification and example should match up.  If it doesn't matter which 
is used then I would say that fixing the example as above is easier that 
changing/fixing the description of the RESTCONF module definition in 
section 8.

Rob