Subject: [Netconf] RESTCONF capabilities and optional features solution proposal

From: Andy Bierman <[email-masked]>
Date: Tue, 26 Aug 2014 09:10:29 -0700

Hi,

The WG agreed at the last IETF to identify protocol capabilities and
consider base functionality + optional features.

Solution proposal:

A) Add following data to /restconf container:

  container parameters {
    list parameter {
       description "Query parameters supported by the server.";
       key name;
       leaf name {
          type string;
          description "Parameter name (e.g. 'depth')";
       }
       leaf organization {
          type string;
          mandatory true;
          description "Parameter organization (e.g. 'ietf.org or example.com
')";
       }
     }
  }

 container capabilities {
    leaf-list capability {
       type inet:uri;
       description "Protocol capability identifier.";
    }
  }

B) Make all query parameters optional to implement
C) Server MUST advertise the parameters it supports.
D) No change in RESTCONF protocol operation requirements
E) Specify 2 URIs (1 for XML and 1 for JSON format)
F) Server MUST advertise at least 1 of (JSON  or XML) URIs
G) Move complex retrieval (collection resource, pagination, etc.)
    to a new document, but leave query parameters already defined
    in RESTCONF

Andy

---

From: Kent Watsen <[email-masked]>
Date: Tue, 26 Aug 2014 17:22:12 +0000

I've heard this approach mentioned before  having all query params be
optional but otherwise the base protocol is unchanged.  It seems to be a
clean way to approach modularity, but what about:

1. Servers that don't want to support sub-URLs.  That is, they only want
to support reading/writing the entire config.

2. Normal HTTP would have a POST to a resource create that resource, but
REST APIs usually have a POST to a "collection" add an entry to the
collection (not create a new collection).    I fully support moving
"collection" support to another document, but I'm unsure how it could
build on top of this "base" definition.

Resolving these, can we consider the base protocol only supporting a
top-level resource/URL and then leave it to another draft to fill in
support for nested URLs and collections?

> E) Specify 2 URIs (1 for XML and 1 for JSON format)

This is usually done via media-type: foobar+xml or foorbar+json  - is
there a reason to use URIs?

Thanks,
Kent

From:  Andy Bierman <[email-masked]>
Date:  Tuesday, August 26, 2014 at 9:10 AM
To:  NetConf <[email-masked]>
Subject:  [Netconf] RESTCONF capabilities and optional features
solution	proposal

Hi,

Solution proposal:

  container parameters {
    list parameter {
       description "Query parameters supported by the server.";
       key name;
       leaf name { 
          type string;
          description "Parameter name (e.g. 'depth')";
       }
       leaf organization {
          type string;
          mandatory true;
          description "Parameter organization (e.g. 'ietf.org
<http://ietf.org> or
example.com <http://example.com>')";
       }

     }
  }

 container capabilities {
    leaf-list capability {
       type inet:uri;

Andy

---

From: Andy Bierman <[email-masked]>
Date: Tue, 26 Aug 2014 10:51:26 -0700

> to support reading/writing the entire config.
This isn't very REST-like though.
We also don't have a good definition of "constrained".
I don't really agree that only reading/writing the entire config is a
limitation
that should be in the standard.

> build on top of this "base" definition.
We do not require every list to be in ots own container, to mimic this
collection approach.
IMO the current approach works for the resource mapping we defined for YANG.
I think a new draft could just invent a new media type
in order to distinguish a new type of POST for RESTCONF.

> support for nested URLs and collections?
I do not want existing RESTCONF to split into multiple documents,
or support a "base" protocol that only supports one giant "datastore"
resource.
Such a device does not really need a modular solution like RESTCONF or YANG.

> there a reason to use URIs?
That is what we use for generic capabilities.
There should be something for the client to read.
It could be a separate leaf:

  /restconf/encoding

   leaf encoding {
      type bits {  // not allowed to be empty
        bit xml;
        bit json;
     }
     mandatory true;
  }

Andy