Subject: [Netconf] RESTCONF JSON list questions

From: Nick Weeds <[email-masked]>
Date: Thu, 14 Jul 2016 16:48:25 +0000

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.