Re: [Netconf] RESTCONF JSON list questions

[Nick Weeds <[e-mail]>]

Hi Mahesh,

The answer to question (2) is that list entries should always be encoded as JSON lists even when there is only one entry.  This is fixed in the latest restconf draft.

I didn't really get an answer to question (1) other than "check the WG mailing list".  However, a subsequent discussion on the WG mailing list with subject "restconf confusing text" raised the same issue.  I think the official view is that restconf does not support querying a list because a list is not a single "data node", and that a future restconf collections draft would provide this kind of function.  I don't think Dale Worley agrees with that position and/or my summary of it.  Also note that it is possible to query a list by using a parent container as the target together with a "fields" query parameter to select the list, so it is possible to query a list using restconf but in a more fiddly way.

               Nick.

From: Mahesh Jethanandani [mailto:[e-mail]]
Sent: 08 September 2016 15:58
To: Nick Weeds
Subject: Re: [Netconf] RESTCONF JSON list questions

Did you ever get a response to your questions below?


Subject:

[Netconf] RESTCONF JSON list questions

Date:

Thu, 14 Jul 2016 16:48:25 +0000

From:

Nick Weeds <[e-mail]><mailto:[e-mail]>

To:

[e-mail]<mailto:[e-mail]> <[e-mail]><mailto:[e-mail]>


I have a couple of questions on RESTCONF handling of Yang lists when using JSON encoding.
Please can anybody answer or clarify these points ?
The current drafts don't seem to give definite answers (or might contain errors), and it's hard to find answers in the archives.


(1)    Is it valid to perform a GET on an entire list rather than a single list entry ?

For example, is it valid to send a GET request for the interface list:

               GET /restconf/data/interfaces/interface

rather than a GET request on for a particular interface list entry:

               GET /restconf/data/interfaces/interface=eth1

Observations:
-        RFC 6020 seems to say that list entries are data nodes but lists are not (sections 3, 4.2.2.4, 7.8).
-        draft-ietf-netconf-restconf-15 seems to say that list entries are data resources but lists are not (section 3.5).
-        draft-ietf-netconf-restconf-15 section 3.5.3 says that the URI must include the key values (so that it identifies a list entry rather than a list), but it doesn't say what happens if the list doesn't have any keys (as is typical for a GET).
-        draft-ietf-netconf-restconf-15 section 4.3 says that a GET cannot return more than one instance when using XML encoding, but it doesn't say what happens when using other encodings (such as JSON).  This seems to keep the possibility of JSON providing more function than XML, although some WG mailing list discussions seem to have argued for keeping strict equivalence.


(2)    When a RESTCONF request contains a single list entry, when should it be encoded as a JSON list and when should it be encoded as a single JSON object (examples in draft-ietf-netconf-restconf-15 vary) ?
For example, when should an album list entry be encoded like this:

        "example-jukebox:album" : [
          {
            "name" : "Wasting Light",
            ...
          }
        ]

and when should it be encoded like this:

        "example-jukebox:album" : {
          "name" : "Wasting Light",
          ...
        }

draft-ietf-netmod-yang-json-10 section 5.4 describes how to encode a list but not how to encode a single list entry in isolation.

Examples in draft-ietf-netconf-restconf-15 seem to vary:
- PUT examples seem to use a JSON list (section 4.5)
- GET example seem to use JSON list (section 5.3.2, D.3.9)
- POST examples seem to use a single JSON object without a JSON list (sections D.2.1, D.3.4, D.3.5).

The earlier "data format for list entry" discussion on the WG mailing list seems to indicate that the PUT and GET examples are correct but the POST examples are wrong.  Is that true?

               Nick.
<Attached Message Part.txt>

Mahesh Jethanandani
[e-mail]<mailto:[e-mail]>