Subject: [Netconf] RP partial comments on draft-ietf-netconf-restconf-09

From: Randy Presuhn <[email-masked]>
Date: Fri, 22 Jan 2016 16:49:55 -0800 (GMT-08:00)

Hi -

Here are my partial comments on draft-ietf-netconf-restconf-09.
I promised to have something by today, but was not able to get
through the entire document - it's slow going for a non-netconf
person!

General stylistic comment:
  The tone of the opening portions of the draft seemed like marketing
  rather than specification.  Some passages may have been
  intended to provide the rationale for specific design
  decisions, but lacked the context and level of detail
  needed to be useful to someone considering implementation,
  deployment, or use of this technology.

Serious, easily fixed problem:
   The draft is filled with occurrances of "&#8209;"  As
   far as I can tell, every single one of theme should
   be replaced with "-".  

Section 1:
  Third paragraph:  the all-caps term RESTCONF is instroduced
  without definition or acronym expansion. Why all-caps?

Section 1.1:
  First paragraph:
  Requirements without justification or clear motivation
  (e.g. "does not need to mirror the functionality of the
  NETCONF protocol") and ones that are unduly vague (e.g.
  "needs to be compatible with NETCONF" - which BTW seems
  to directly contradict the previous stated requirement)
  are not helpful.  Suggest rephrasing in terms of what
  this protocol *is* or *does*, rather than waving around
  ill-defined requirements.

  Second paragraph:
  "Edits are usually applied to one data resource instance at a time."
  The word "usually" provides no guidance and has no normative force.
  This statement isn't helpful, so I suggest deleting it.

  Third paragraph:
  "The base RESTCONF protocol is intentionally simple to allow
  deployment for as many use cases as possible."  How does simplicity
  increase the number of use cases that can be addressed?

  Fourth paragraph:
  The term/acronym "REST" is used without prior definition or reference.

Section 1.2
  First paragraph:
  The term acronym "HATEOAS" is used without prior definition or reference.

  I found this paragraph is general to be quite unhelpful - it doesn't
  say how this protocol does anything, yet brings in undefined terms,
  e.g. "resource endpoint".  I suggest deleting the paragraph.

  Second paragraph:
  This paragraph describes a strategy *not* employed by this protocol.
  This is not helpful information.  Delete it.

  Third paragraph:
  This adds nothing to the specification.  Delete it.

  Fifth paragraph:
  What is this paragraph trying to say?  For SNMP, the location
  of information is very much tied down by the schema.  I don't
  get the point of whatever contrast the authors are trying to
  draw here.

  Sixth paragraph:
  The introduction talked about datastoreS, but this paragraph and the
  following make it sound like there is only a single datastore.  Which
  will it be?

Section 1.3
  Second paragraph:
  "The candidate is automatically committed to running after a
   successful edit."  Replace "a" with "each" - that's what's
   meant, right?

  Third paragraph:
  "after" - leads to two questions: "how long after?" and
  "after each edit?"

page 10 "HTML5" - no reference?  From context, assume this should
   be a normative reference.

2.3
  The text considers three of four possibilities.  What happens
  in the case not spelled out, to wit, when X.509 certificate
  path validation fails and the presented X.509 certificate
  *DOES* match a locally configured certificate fingerprint?

2.5
  Second paragraph - this seems like an inappropriate use of
  MUST, at least as the text is currently structured.  The
  first sentence says something must be done in one of two
  ways.  The next sentence that an implementation-specific
  approach is also allowed.  That means the "MUST" is really
  an option, so using "MUST" doesn't make sense.

  Third paragraph - "RESTCONF client identity" perhaps my SNMP
  orientation is showing, but for purposes of access control,
  wouldn't one want to draw a clear distinction between "client
  identity" and *user* identity?  Both matter, but it seems to
  me that they're different things.

3
  First paragraph:
    "Each resource represents a manageable component within the device."

  Is this intended to prohibit the use of this protocol to manage
  components external to the device, as in various kinds of proxy?
  It seems that this would interact badly with the various "mount"
  proposals.

  Does this require that the manageable component actually exists?
  if not, then perhaps it might be better to say something like
  "potential manageable component"

  Second paragraph:  what is "conceptual" data?

  Third paragraph:
   "A resource has its own media type identifier..."  are the words
   "its own" intended to convey some meaning other than "a"?

  Fourth paragraph:
    "All RESTCONF resources are defined in this document..."

    It sounds like "resource types" is intended.

  Last paragraph:
     I'm not able to reconcile this paragraph with the immediately
     following section, number 3.1.  If this paragraph *is* correct,
     how does it interract with the various moutn point proposals?

3.1
  First paragraph: the "MUST" seems overstated.  Failure to execute
  this step in this manner does not necessarily result in a failure
  to interoperate.  At most this should be a "SHOULD", and even then
  it seems contrary to RFC 2119's guidance to be sparing in the use
  of these words.

  Second paragraph: "Once discovering the RESTCONF API root" 
   The English is broken.

3.3.2
  Since this facility is described as *COMPLETELY* optional, it
  does nothing to foster interoperability.  Either change the
  "MAY" in the second paragraph to a "MUST", or remove this
  section.

3.4
  I'm having a hard time reconciling the straightforward notion
  of datastore presumed by this section with the rather baroque
  facilities needed to support some of the alternatives being
  discussed with regard to operational / state data.  In particular,
  I'm worried about the "all" in the statement that "[t]he RESTCONF
  datastore resource is a conceptual collection of all configuration
  and operational data that is present".  To me this implies the
  ability to explicity distinguish / access, for example, both
  "intended" and "applied" versions of a configuration parameter.
  The phrase "on the device" seems to be intended to exclude use
  with proxy technologies.

3.4.1
  This is in the datastore resource section,  but talks about the
  data resources.  This seems odd.
  Why are two mechanisms mandated?
  Why is no comparable mechanism provided for non-configuration data?

3.4.1.1
  The text describing the maintenance of last-modified seems incomplete.
  As a read the current text, in a server maintaining only a timestamp
  for a parent resource, modification of a child resource's configuration
  data doesn't cause the parent's timestamp to change.  I think these
  algorithms make some big unspoken assumptions about timestamp
  propagation within a tree.

3.4.1.2
  Same comment as for 3.4.1.1

3.5
  "For configuration data resources, the server MAY maintain a last-
   modified timestamp for the resource, and return the "Last-Modified"
   header when it is retrieved with the GET or HEAD methods."  Making
   returning the "Last-Modified" header OPTIONAL here seems at odds
   with 3.4.1.1.  Likewise for etags and 3.4.1.2.

   Last paragraph: what is the resource definition version in the
   case of an undated module?
 
3.5.1
  Third bullet - shouldn't there be an "=" in there somewhere, as
  there is in the second bullet for the single-key case and as
  shown in the example?

3.6
   "If the "action" or "rpc" statement has an "input" section, then a
   message-body MAY be sent by the client in the request, otherwise the
   request message MUST NOT include a message-body."

   This seems odd.  Why is the MAY only a MAY?  If the action/rpc
   has an input section, what does it mean to omit the message-body?
   Why is the MUST NOT *necessary*?  What would *break* if such an
   unexpected message-body were sent?

   "If the operation is successfully invoked, and if the "action" or
   "rpc" statement has an "output" section, then a message-body MAY be
   sent by the server in the response, otherwise the response message
   MUST NOT include a message-body in the response message, and MUST
   send a "204 No Content" status-line instead."

   This, too, seems odd.  Why is the message-body optional for actions/
   rpcs with output statements?  What does it mean when the message body
   is omitted in such cases?  Why is the MUST NOT *necessary*?  What
   *breaks* if an unexpected (empty) message-body is sent?

   "If the operation is not successfully invoked, then a message-body
   SHOULD be sent by the server, containing an "errors" resource, as
   defined in Section 3.9."

   Is this intended to mean that it would be ok for the server
   to give no response at all, or to give a message-body
   containing some other information?

3.6.3
   is what is here called an '"errors" data structure' the same thing
   as what is called an '"errors" resource' earlier in the document?

3.9
   How does one reconcile this explanation with earlier references
   in the document to an '"errors resource"?

Section 4
  Fourth paragraph:

  Is it really intended to make access control OPTIONAL?  This
  seems a serious shortcoming, and seems somewhat at odds with
  the fifth paragraph.

4.1
  What is the interoperability benefit of making this facility optional?
  Suggest making it mandatory or removing it altogether.

  Third paragraph: is this intended to mean that support for OPTIONS
  is MANDATORY whenever PATCH is supported?

4.3
  Third paragraph: "an error response containing a "403 Forbidden" or
   "404 Not Found" status-line is returned to the client."  How
   does the server decide which of these two?  Consistently returning
   404 would fit the SNMP world-view.

4.4.1
   "an error response containing a "403 Forbidden" or "404 Not Found" 
   status-line is returned to the client."  How does the server
   decide?  Consistently returning 404 would seem to leak less.

4.4.2
   " an error response containing a "403 Forbidden" or "404 Not Found"
   status-line is returned to the client"  Pick one.

4.5
  "If an existing resource is modified, either "200 OK" or "204 No
   Content" are returned."  Pick one or give the criteria for deciding
   which one to use.

   "an error response containing a "403 Forbidden" or "404 Not
   Found" status-line is returned to the client"  Pick one or give
   the criteria for deciding between them.

4.6
   "a "403 Forbidden" or "404 Not Found" status-line
   is returned to the client."  Pick one or give criteria for deciding
   which to use.

4.7
   "a "403 Forbidden" or "404 Not Found" status-line
   is returned to the client."  Pick one or give criteria for deciding
   which to use.

Section 10:
  This section strikes me as rather odd.  It feels like it's
  using some HTTP-specific hacks to accomplish query optimizations
  that more properly should have been done through the information
  model.

Section 10.1.1
  paragraph 3:
   "The server MAY maintain a last-modified timestamp for each instance
   of this list entry, and return the "Last-Modified" header when this
   data node is retrieved with the GET or HEAD methods.  If not
   supported then the timestamp for the parent "modules" container MAY
   be used instead."

      This text baffles me.  Section 10.1 makes support for timestamping
      "modules" mandatory.  The second sentence here makes it optional.
      This makes no sense.  I suggest deleting the second sentence.

  paragraph 4:
   "The server MAY maintain an entity-tag for each instance of this list
   entry, and return the "ETag" header when this data node is retrieved
   with the GET or HEAD methods.  If not supported then the timestamp
   for the parent "modules" container MAY be used instead."

     Likewise baffling.  Delete the second nonsensical sentence.
 
Section 11.1
  Why both "RFCXXXX" and "RFC XXXX"?

Section 11.3
  Does the "xxx" have any relationship to the "XXXX" in this section?

Section 12
  Last paragraph:
   "Note that authorization information can be
   exchanged in the form of configuration information, which is all the
   more reason to ensure the security of the connection."
  I think "authentication" rather than "authorization" is intended here.

Did not look at appendix A or appendix B.
Do not have tools to verify appendix C or D,
made no attempt to manually work through all that stuff.

Randy