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

[Andy Bierman <[e-mail]>]

On Tue, Dec 3, 2019 at 7:46 AM Martin Bjorklund <[e-mail]> wrote:

> 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.
>
>

I agree with Martin about designing for RESTCONF when YANG is used for
several protocols.
(E.g. extra containers could mean extra keywords in the CLI)

A parent container does solve some protocol deficiencies in NETCONF and
RESTCONF
but we should resist strict CLRs and decide each case on its merits.

I am far more concerned about the style of organizing and publishing
groupings instead of accessible objects.
Just try implementing YANG Push/SN and you will see what I mean. The same
groupings used in different
places have different implementation details.  Most of the details are not
explained at all in the YANG object because the
grouping descriptions are intended to be context independent.  The
descriptions in "uses" subtrees in each context
are terse or non-existent.  Perhaps developers will make the same
implementation decisions. Perhaps not.
There are 100s of details spread out in the RFCs outside the YANG objects,
which makes sense for this
protocol and context independent approach, but makes development much more
complex.



> /martin
>
>
Andy


>
>
> > 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
>
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors
>