Subject: [Netconf] yang api question

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 12 Feb 2013 16:14:02 +0100

Hi,

I have a question concerning the YANG API draft. If I have a data model
that is nested lets say three levels deep,

a {
  b {
    c {
    }
  } 
}

does a server need to implement all possible datastore resources,
that is:

     /yang-api/datastore/a
     /yang-api/datastore/a/b
     /yang-api/datastore/a/b/c

Note that not all those resources may be 'useful' to support, the
closer you get to the root, the larger the data gets one is operating
on.

/js

PS: Did you really mean this:

   A RESTful client using YANG-API will not use any data modelling
   language to define the application-specific content of the API.  The
   client would discover each new child resource as it traverses the
   URIs return as Location IDs to discover the server capabilities.

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 12 Feb 2013 16:39:21 +0100 (CET)

>      /yang-api/datastore/a/b/c

Currently the answer is "yes".  But there is an open issue listed in
section 12

   o  Should every YANG data node be a data resource and every YANG RPC
      statement an operation resource?  Is a YANG extension needed to
      allow data modeler control of resource boundaries?

Maybe you have some experience regarding this?

>    URIs return as Location IDs to discover the server capabilities.

This goes back to what RESTful really means.  It seems that from a
pure REST point of view, clients should treat the URIs as opaque
strings.  A proper RESTful client would never construct a URI; it
would just follow links.  YANG-API supports such clients, while at the
same time it also supports clients that do construct URIs.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Feb 2013 07:45:52 -0800

>      /yang-api/datastore/a/b/c
Good question -- it probably depends on the method.
GET, DELETE, PUT -- yes. PATCH maybe. POST may
be up to the capabilities of the server.

I have found a couple major design flaws during my implementation
that the WG should probably know about:

1) list and leaf-list targets for GET that return multiple instances
    need a <data> wrapper for XML encoding or else the response will
    not be a valid XML document.  JSON does not have this problem.
    There is no XML namespace defined yet for <errors> or this <data>
wrapper.

2) retrieval of 'config=false only' could be very expensive to implement in
an
    optimized (streamed) manner because scaffolding nodes (containers,
lists that
    are config=true) need to be generated before the server knows if any
instances
    of the config=false nodes exist, and pass NACM and other filtering.
    Since config=false nodes can never contain config=true nodes, the
pruning
    for current <get-config> is trivial.

Few observations:
  - the distinction between fields and resources is artificial and not
useful.
    My implementation is aligning with <get2> and just treating each nest
level
    as a new level wrt/retrieval filtering
  - netconf-monitoring and notifications are supported (except start-session
    and end-session are not sent).  NETCONF monitoring is somewhat deficient
    for multiple protocols.  It is not clear which counters (if any) apply
to YANG-API
    requests.
 - It is not clear when a 404 Not Found status would be returned. The draft
   says to return 400 Bad Request for unknown resources.

> closer you get to the root, the larger the data gets one is operating

The server may need to restrict how many resources can be edited at once.

>    URIs return as Location IDs to discover the server capabilities.
No -- this should have been removed.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 12 Feb 2013 18:29:37 +0100

> Maybe you have some experience regarding this?

I would not say experience, just that it sounds a bit too much. ;-) 
 
> same time it also supports clients that do construct URIs.

But this text seems to be in conflict of lots of stuff that follows.
Anyway, why not have the resource URLs derived from the data model but
allow servers to announce the resources they actually provide. The client
would then discover whether a server only implements

  /yang-api/datastore/a/b

or multiple of those nested resources. Of course, this moves some work
towards the client since the client now needs to adapt to what the
server provides. But servers not running a full-blown NETCONF engine
in the back will likely become somewhat simpler.

/js

PS: I have no implementation experience with this yet. So I am just
    asking questions at the moment (although there are reasons for
    asking these questions ;-).

---

From: Kent Watsen <[email-masked]>
Date: Tue, 12 Feb 2013 18:40:07 +0000

>  /yang-api/datastore/a/b/c

When we were designing the REST API for our NMS, an ex-colleague of mine
related horror-stories about how this strategy played out for him before.
Essentially, he said the bookkeeping was a nightmare.  Based on this we
decided to use FILTERING for granular-reads and PATCH for granular-writes.
 That said, we also partitioned our resources as being either an "object"
or a "collection" (though we support both primary and secondary
collections).  For instance, in our system, the following would be legal
resources:

  /users               (a primary collection of user-hrefs with some
pull-thru data)
  /users/33            (user #33)
  /alerts              (a primary collection of alert-hrefs with some
pull-thru data)
  /alerts/21           (alert #21)
  /users/33/alerts     (a secondary-collection of user 33's alerts)
  /users/33/alerts/21  (an href to alert #21, this resource could be
DELETE-ed)

While none of the following would be legal:

  /users/33/name
  /users/33/name/first
  /users/33/name/last
  /users/33/address
  /users/33/address/street

  /users/33/address/city

  /users/33/address/state

A couple comments about our strategy:

  1. We always use system-generated ids for primary keys.  We find this
helps
     maintain referential integrity while not being overbearing, since the
     hrefs are always returned (clients don't have to cook those URLs).  We
     also support secondary keys so collections can be conveniently
searched
     (i.e. find users with last name "smith" and live on a street that
contains
     the substring "parkway")

  2. Each of our resources (i.e. objects and collections) are
strongly-typed.
     We use a custom media-type that maps directly to a data-model - we
use 
     XSD, but there's no reason why it couldn't be YANG.

>> same time it also supports clients that do construct URIs.

We found that this Fielding's vision for HATEOAS was only realizable if
there were standard media-types for everything.   In the world of
web-browsers, it's conceivable to have media-type definitions for all the
various image/sound/video resources, and the Atom Protocol does a decent
job for RSS feeds, but the reality is that most our clients are NOT
generic web-browsers, they are NMS/OSS apps - that said, our NMS's
web-based GUI does use the REST API too, but only after downloading tons
of business-logic specific JavaScript (far from being generic).  This is
why we decided on using custom media-types...

Thanks,
Kent

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Feb 2013 10:59:41 -0800

> I would not say experience, just that it sounds a bit too much. ;-)
Correct.
Some options:
  1) exclude a hard-wired set (like all netconf, create-subscription)
  2) create a YANG extension to tag the rpc-stmts that should
      be accessible via YANG-API
  3) let the vendor choose

There isn't any extra implementation cost to allowing access to
all the RPCs that NETCONF can invoke -- just a matter if is
the right thing to do or not for YANG-API.

I think (3) is good enough.

Andy

> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>