Re: [yang-doctors] Consistency for naming lists and leaf-lists

[Martin Bjorklund <[e-mail]>]

Hi,

Kent Watsen <[e-mail]> wrote:
> Hi Rob,
> 
> > Can't we just say that lists SHOULD NOT be put in their own containers
> > to wrap the list?
> 
> If we were to pick a default stance, though I'm hesitant to think we
> should, I'd recommend the opposite, that containers SHOULD be used to
> wrap lists (and this strategy is used in all the models in the drafts
> I'm authoring).

I think that NP-containers should be used when they make sense from a
modelling pow, i.e., to provide structure to the nodes.  In most cases
such containers are not needed.  I do not agree that it is a good idea
to put a surrounding container on *all* lists just for the sake of it
(and eventually I am going to send comments re this and other things
like naming in your drafts, but not until we have agreement on the
basics).

> I feel that this is conceptually more accurate.  That is, what we call
> a "list" is really a list-element, hence why it should have singular
> name.  A wrapping-container, having a plural name, gives it the
> appearance of it being a collection at first glance (e.g., "/widget"
> vs. "/widgets/widget").
> 
> In REST APIs, clients create new list-elements by POST-ing to the
> parent resource, which acts as the list, supporting query options for
> sorting, filtering, searching, and pagination.  While it is possible
> to have heterogeneous contents (i.e., using media-types), it's most
> common for the contents to be homogeneous.  Any search for "REST API
> collection best practice" shows this.

I know it is common that REST apis are structured like this.  But a
YANG model is not a defintion for a REST interface; rather, RESTCONF
is one of many ways to access data modelled in YANG.

A good structure, just like good names, matter, even though we discuss
programmatic interfaces.



/martin



> The issue we're having is what might be called an "impedance
> mismatch".  In YANG, the list-element is the "list", but the parent
> node is rightfully the "collection".
> 
> Notably,
> https://tools.ietf.org/html/draft-ietf-netconf-restconf-collection
> <https://tools.ietf.org/html/draft-ietf-netconf-restconf-collection-00>
> effectively bucks REST API best practice, targeting the
> collection-oriented operations to the "list element" resource.
> Accordingly, this resulting RESTCONF API is both asymmetric and
> different than most other REST APIs.  For example (simplified for
> brevity):
> 
> 	To insert a new widget into the collection:
> 
> 		POST /widgets
> 
> 	To get widgets in the collection:
> 
> 	 	GET
> 	 	/widgets/widget?limit=2&offset=3?sort=name?where='foo==bar'
> 
> 	(both are "collection" operations, but act on different resources)
> 	
> It is understandable why the "restconf-collection" draft takes the
> approach it does, it being the logical result of YANG allowing a
> container to having more than one 'list' descendant.  But, if we were
> ever to pick that draft up again, or perhaps as part of YANG-next, we
> could define a "collection" annotation for containers (or a
> "collection" statement) that would: 1) signal that the container
> contains exactly one list and 2) allow the list-operations to be
> targeted to the container resource.
> 
> In the meanwhile, while waiting for the "collections" work to be
> picked up again, I feel that the YANG best practice, if anything,
> should be to mimic this structure (a container wrapping each list).
> 
> Kent