Re: [Netconf] Fwd: I-D Action: draft-bierman-netconf-restconf-03.txt

[Martin Bjorklund <[e-mail]>]

Wojciech Dec <[e-mail]> wrote:
> On 10 January 2014 19:48, Martin Bjorklund <[e-mail]> wrote:
> > Wojciech Dec <[e-mail]> wrote:
> >> Hi Martin,
> >>
> >> On 10 January 2014 16:25, Martin Bjorklund <[e-mail]> wrote:
> >> > Wojciech Dec <[e-mail]> wrote:
> >> >> Hi Martin,
> >> >>
> >> >> On 8 January 2014 12:29, Martin Bjorklund <[e-mail]> wrote:
> >> >> > Wojciech Dec <[e-mail]> wrote:
> >> >> >> On 6 January 2014 12:49, Andy Bierman <[e-mail]> wrote:
> >> >> >> >
> >> >> >> >
> >> >> >> >
> >> >> >> > On Mon, Jan 6, 2014 at 3:33 AM, Wojciech Dec <[e-mail]>
> >> >> >> > wrote:
> >> >> >> >>
> >> >> >> >> Hi Andy, all,
> >> >> >> >>
> >> >> >> >> are the issues leading to this draft documented somewhere? The IETF
> >> >> >> >> 88 minutes only talk about the yang patch aspect.
> >> >> >> >>
> >> >> >> >> Anyway, I took a read through the latest document and the change to
> >> >> >> >> have all Yang data-nodes be resources. Am I correct in interpreting
> >> >> >> >> it
> >> >> >> >> that now  every leaf node  effectively becomes a resource with a
> >> >> >> >> separate URI? Could the authors provide some more insight regarding
> >> >> >> >> this change?
> >> >> >> >>
> >> >> >> >
> >> >> >> >
> >> >> >> >
> >> >> >> > Since YANG Patch is now optional, there is no way to delete an
> >> >> >> > optional
> >> >> >> > leaf
> >> >> >> > or leaf-list otherwise, except to copy the entire resource, and then
> >> >> >> > replace
> >> >> >> > the entire resource (minus the optional leaf).
> >> >> >>
> >> >> >>
> >> >> >> I am still not able to get the full rationale for the change.  Can the
> >> >> >> authors or chairs provide that?
> >> >> >>
> >> >> >> Anyway, it now appears that every single data leaf is a resource,
> >> >> >> instead of an attribute
> >> >> >
> >> >> > Yes, every leaf is a subresource to its parent list or container.
> >> >> > This just means that you can GET/POST/DELETE the leaf directly, w/o
> >> >> > having to PATCH the parent.
> >> >> >
> >> >> >> and the spec doesn't specify a distinction
> >> >> >> between handling parent resources and its sub-resources, e.g. At the
> >> >> >> very least POST/PUT operations to sub resources need to be constrained
> >> >> >> by their parent resource, and leaving that up to the implementation is
> >> >> >> kind of a step backwards for the spec as a whole besides being IMO a
> >> >> >> major complication for client or server, and likely both e.g how
> >> >> >> should a change to a sub-resource that doesn't meet some condition of
> >> >> >> the parent be handled? For a single parent resource, how should
> >> >> >> multiple sub-resource changes be coordinated (the parent resource
> >> >> >> needs to be consistent)? Etc.
> >> >> >
> >> >> > I am afraid I do not understand your concern.  Could you provide an
> >> >> > example (data model and requests) that you feel is problematic or
> >> >> > unclear?
> >> >>
> >> >>
> >> >> A simple example:
> >> >>
> >> >>     container book {
> >> >>
> >> >>                 leaf price {
> >> >>                      type string;
> >> >>                  }
> >> >>                 leaf tax-amount {
> >> >>                      type string;
> >> >>                  }
> >> >>
> >> >>      }
> >> >>
> >> >> Price and taxt are typically related.
> >> >> A (better) REST API design would seek to minimize transactional
> >> >> effects to the client while protecting the consistency/sanity of the
> >> >> data: To update the resource, a POST operation to foo/book would carry
> >> >> in the envelope both a new price and the tax amount. A (worse) REST
> >> >> API design would expose both price and tax-amount as separate
> >> >> resources, accept POST to both foo/book/price and foo/book/tax-amount
> >> >> and hope-for-the-best that the client succeeds and all. Several non
> >> >> trivial failuire scenarios come up here too.
> >> >
> >> > Note that with the current design, you get both, and the client can
> >> > choose to use the resource that fits his needs best.  Specifically,
> >> > book is still a resource, so if the client wants to update both leafs
> >> > in one transaction, it would POST to the book resource.
> >>
> >> Well, ok, but how can the server assume what he client chooses to do,
> >> other than supporting every possibility. Or alternatively, how can we
> >> tell the client: "Although RESTCONF spec + YANG model might indicate
> >> otherwise, leafs are not resources in our implementation"?
> >
> > The server still has to support the relevant operations on the leaf
> > resources, but the client can choose to not use them if it wants to.
> >
> > See also below.
> >
> >
> >> >> The key is that REST API design is very much about determining what is
> >> >> a resource,  its representation by a URI, and what are the attributes
> >> >> of a resource. In draft -03, everything is now a resource, and
> >> >> everything is also attribute. This IMO ultimately complicates and
> >> >> bloats code (on client, server, and likely both)
> >> >
> >> > In our server we actually had special code to handle the case that
> >> > leafs were not resources.  So in our case the code is now simpler.
> >> >
> >> > On the client side I do not know.  But again note that the client can
> >> > choose to treat all leafs as attributes if it wants to.
> >> >
> >> >> and will lead to
> >> >> brittle API and poor user experience.
> >> >>
> >> >> Another quick example:
> >> >>
> >> >>
> >> >>     container book {
> >> >>
> >> >>                 list page {
> >> >>                     key page-nr;
> >> >>                     leaf page-nr {type string;}
> >> >>                     leaf text {type string;}
> >> >>                  }
> >> >>      }
> >> >>
> >> >> The RESTConf URI for the above would <root stuff
> >> >> here>/book/page/{page-nr}/text
> >> >>
> >> >> In general with REST APIs it is important that we do NOT expose the
> >> >> dependent sub-resources directly thus allowing someone to create (POST
> >> >> or PUT) to <root stuff here>/book/page/{page-nr}  without a book, or
> >> >> text without a page, or other cases that do not make sense
> >> >
> >> > Without a book doesn't work since a page is defined under the book.
> >> > In general, such constraints should be expressed in the data model
> >> > (with proper containment and/or must / unique / mandatory etc
> >> > constraints).  This separates the semantic correctness of the instance
> >> > data from the specific API details used to change the underyling
> >> > data.  This is especially true of we want to support multiple
> >> > protocols (which is what we're doing with RESTCONF).
> >>
> >> Yeah, but how would one do that...
> >>
> >> >
> >> >> , and in
> >> >> general requiring a feast of error cases.
> >> >> Requiring the text POST/PUT  handler to also do book creation,
> >> >> validation, etc, is not a great design.
> >> >
> >> > Agreed, but that is not the intention.
> >>
> >> ... without ending up with the above, or assuming a very very specific
> >> data store ? Or perhaps, that's the thing I'm not understanding: what
> >> is the responsibility of RESTconf layer and what is the responsibility
> >> of the data store in terms of the yang schema?
> >
> > If the server gets a request from a client to set the title of a book:
> >
> >   PUT /.../book/{book-name}/page/{page-nr}/text
> >
> > and the book doesn't exist, the server signal an error.  It will not
> > automatically create the book.
> 
> Sure, I know that this should happen, but what is the responsibility
> of RESTconf layer and what is the responsibility
> of the data store in terms of the yang schema?
> Currently it appears that Restconf assumes that the whole resource
> containment (model enforcement) is assumed to be done by the data
> store.

This is up to the implementation.  In a multi-protocol implementation
one might think that the underlying datastore takes care of the "model
enforcement", but nothing prevents you from doing everything in the
RESTCONF layer.


/martin