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

[Martin Bjorklund <[e-mail]>]

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.

(this example made the book a list, not a container)


/martin