[SOLVED] Is it legal to GET all list instances in RESTCONF?

Is it legal to GET all list instances in RESTCONF?

Given the following YANG definitions, in module test:

list machine {
    key "name";
        leaf "name" {
        type string;
    }
}

and in data tree:

"machine" : [
    { "name": "a" },
    { "name": "b" },
    { "name": "c" }
]

I want to know if the following request conforming to RESTCONF?

GET /restconf/data/test/machine

This request is expected to return all the list instances.

I have this question because I don't have a clear understanding of the words from RESTCONF. In RESTCONF 3.5.3,

If a data node in the path expression is a YANG list node, then the key values for the list (if any) MUST be encoded according to the following rules:

o The key leaf values for a data resource representing a YANG list MUST be encoded using one path segment [RFC3986].

o If there is only one key leaf value, the path segment is constructed by having the list name, followed by an "=" character, followed by the single key leaf value.

The (if any) mean which one of the following two meanings? (the key statement is not a must for a non-configuration list. So there are keyed lists and non-keyed lists.)

Users are free to specify key values for keyed lists. The (if any) is about "if the key values are specified." If they specify then the key values MUST follow the rules about the key values. If they don't specify then you don't have to follow the rules about key values. Take my YANG definitions for example, these two requests are both correct:
```
 GET /restconf/data/test/machine    // get all list instances
 GET /restconf/data/test/machine=a  // get the list instance keyed "a"
```

Users have to specify key values for keyed lists. The (if any) is about "if the list is keyed or not." In this understanding, there will be:

 GET /restconf/data/test/machine    // wrong request, can't get all list instanecs
 GET /restconf/data/test/machine=a  // ok, get the list instance keyed "a"

The second understanding is from the similar words in the same section for leaf-lists:

If a data node in the path expression is a YANG leaf-list node, then the leaf-list value MUST be encoded according to the following rules:

o The identifier for the leaf-list MUST be encoded using one path segment [RFC3986].

o The path segment is constructed by having the leaf-list name, followed by an "=" character, followed by the leaf-list value (e.g., /restconf/data/top-leaflist=fred).

The words for leaf-lists don't have (if any), so you cannot use a URL like /restconf/data/top-leaflist. You have to use =fred to specify a leaf-list instance. So If leaf-list instances cannot be retrieved as a whole, why list instances can be retrieved as a whole (in understanding 1)? A leaf-list instance and a list instance are both a data resource, they are equivalent in concept.

Thanks,

Solution

The correct interpretation is 1. The "if any" refers to key values, not YANG key statements. It is okay for a RESTCONF GET to fetch more than one instance of a list, but only in JSON encoding (well formed XML does not allow multiple root elements). This is also the only way to retrieve key-less non-configuration (state) list instances.

If only a single list entry would be allowed to be obtained via GET, its corresponding RFC section would explicitly state this with a MUST - if you take a look at the wording for DELETE in section 4.7, p3, such text exists, but there is no equivalent for GET.

It is also okay to retrieve multiple leaf-list instances. This may be the only way to retrieve some such instances, since (in YANG 1.1) duplicate values are allowed for non-configuration leaf-lists. The missing "if any" is most likely an editorial omission.

Note that the text in 3.5.3 only explains how URIs are formed, it does not say anything about how RESTCONF operations utilize those URIs.