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

[Andy Bierman <[e-mail]>]

On Fri, Jan 10, 2014 at 5:39 AM, Wojciech Dec <[e-mail]> wrote:

> On 10 January 2014 11:37, Andy Bierman <[e-mail]> wrote:
> >
> >
> >
> > On Fri, Jan 10, 2014 at 1:37 AM, 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.
> >>
> >> 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), 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, 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. It complicates code and
> >> creates ugly code dependencies, should the model change, etc.
> >>
> >>
> >> >
> >> >> If this current development was driven by questions/problems in the
> >> >> support of HTTP Patch operation (incl. JSON patch), the solution
> >> >> appears to be possibly worse than the supposed problem. That's why it
> >> >> would be good to understand the rationale some more.
> >> >
> >> > If the "yang patch" media type is opitonal, there is no other way to
> >> > delete optional leafs.  If the optional leaf is a resource it can be
> >> > removed with DELETE.
> >>
> >> Yes, but the current "solution" is IMO a lot worse than a) mandating
> >> PATCH, and I mean plain JSON/XML PATCH  or b) handling (specifying in
> >> the draft how-to do) updates via POST. Thus bringing in back the
> >> simple patch would be a good move. And the Yang patch is something
> >> that can go into another spec, I agree.
> >>
> >
> >
> > Plain PATCH does not allow an optional leaf to be deleted.
> > JSON patch does not work well with named data like YANG.
> > Ignoring YANG naming and using integer indices that renumber
> > every time a list is changed is a non-starter.  The only way to
> > delete an optional leaf is to GET the entire parent resource,
> > edit it offline (remove the leaf) and PUT the parent resource.
> > This is operationally disruptive and expensive to implement
> > in the server.  Optional leafs make up most configuration data,
> > so a CM solution that doesn't work well for optional leafs is a bad idea.
>
> I should have been clearer: Media Type discussion aside, I meant JSON
> patch as in "json patch for json reresented yang data", ie likely a
> subset of pure 'application/json-patch+json', with yang-patch being in
> some other doc. . The fact that JSON patch does not work for xml is,
> for me at least, not an issue. A simple answer can thus be that the
> patch is for json only.
> In general, I don't quite follow why you say that json patch doesn't
> allow for leaf deletion; the "remove" op seems to be pretty much
> intended for that. Gee, the json (yang) patch could even be just
> limited to just this task.
>
>
JSON Patch does not work for NETCONF datastores very well
because they contain data named with YANG list keys.  It has
nothing to do with XML.  It has to do with the problems related
to editing foo[i] instead of foo[test1][row2][step3], where "i" is
constantly changing for a given resource.


That said, a solution to the " how to delete an optional leaf" problem
> that ends up treating every data item in the system to a resource,
> with no way for the designer to override, appears also as a bad idea.
> Given that we have a full API spec here, even adding a custom
> parameterized operation to the URI may be a better solution. Also,
> evidence from the REST API world out there also indicates that for
> better or worse, GET and PUT do actually work at scale. I would still
> see this still as easier to deal with and implement than having every
> single (sub-resource) data item as a resource....
>
>
As Martin pointed out, your app can choose not to treat leafs as
resources and everything still works.  What will break in your
application code if you choose to treat leafs as attributes instead
of resources?

IMO, an optional leaf or leaf-list is a sub-resource because it can be
created
and deleted after the parent resource is created.



> So, in summary, "conservative" options, all leading to getting the
> spec back from resource extremes as I see can be:
> 1. Stay with GET and PUT (I suspect that this is what will get most use
> anyway).
> 2. Introduce JSON patching, in the form of say
> "application/yang-json-patch" to the spec (happy to work up some text)
> 3. Get back the "full" yang patch from draft -02
> 4. Introduce a new action/operation invoked via a parameter.
>
>
I don't understand this list, especially 2 & 3.


> Thoughts?
>
> Cheers.
> >
> >
> >>
> >> Cheers,
> >> Wojciech.
> >
> >
> >
> > Andy
> >
> >>
> >> >
> >> > /martin
> >
> >
>


Andy