[yang-doctors] Yangdoctors last call review of draft-ietf-netconf-restconf-client-server-04

Andy Bierman <andy@yumaworks.com> Fri, 28 July 2017 22:16 UTC

Return-Path: <andy@yumaworks.com>
X-Original-To: yang-doctors@ietf.org
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from ietfa.amsl.com (localhost [IPv6:::1]) by ietfa.amsl.com (Postfix) with ESMTP id BC507132302; Fri, 28 Jul 2017 15:16:42 -0700 (PDT)
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
From: Andy Bierman <andy@yumaworks.com>
To: yang-doctors@ietf.org
Cc: draft-ietf-netconf-restconf-client-server.all@ietf.org, netconf@ietf.org
X-Test-IDTracker: no
X-IETF-IDTracker: 6.57.0
Auto-Submitted: auto-generated
Precedence: bulk
Message-ID: <150128020275.20726.13027423171798327745@ietfa.amsl.com>
Date: Fri, 28 Jul 2017 15:16:42 -0700
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/CHWtiIwYjgari1p2v8n97FJEWGU>
Subject: [yang-doctors] Yangdoctors last call review of draft-ietf-netconf-restconf-client-server-04
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.22
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 28 Jul 2017 22:16:43 -0000

Reviewer: Andy Bierman
Review result: Ready with Nits

Review: draft-ietf-netconf-restconf-client-server-04

Modules:
 (M1) ietf-restconf-client@2017-07-03.yang
 (M2) ietf-restconf-server@2017-07-03.yang


YANG Usage:

 I did not find anything wrong in either module.
 pyang and yangdump-pro do not report any errors or warnings.

Comments:

C1:

 (M1) RESTCONF does not have sessions so the term "RESTCONF session"
 needs to be defined

C2:

 (M1) feature tls-initiate
 (M1) feature tls-listen
 (M2) feature tls-listen
 (M2) feature tls-call-home

 Are these features really needed since a RESTCONF server MUST support
 the TLS transport?

C3:

 (M1)  /restconf-client/initiate/restconf-server/persistent/

 RESTCONF has no session setup; It only has request and
 response interactions. The purpose of reconnect, idle timeouts etc.
 are completely up to the client application.

C4:

 (M1)  /restconf-client/initiate/restconf-server/persistent/max-attempts

 What should the RESTCONF client do if a "Connection: close"
 header is received from the server (indicating the server is dropping
 the TCP connection) Should the reconnects proceed?

C5:

 (M1)  /restconf-client/initiate/restconf-server/periodic/


      "Periodically connect to the RESTCONF server, so that
       the RESTCONF server may deliver messages pending for
       the RESTCONF client.  The RESTCONF server must close
       the connection when it is ready to release it.

This is not how RESTCONF works.
The RESTCONF server requires a request message in order to
send content to a client.  I do not understand the use-case
for periodic RESTCONF sessions.

C6:

 (M1)  /restconf-client/initiate/restconf-server/periodic/
 (M2)  /restconf-server/call-home/restconf-client/connection-type/periodic/

 The RESTCONF notifications via SSE should be exempt from timeouts.
 The RESTCONF client should terminate an SSE request. The server should
 not timeout an SSE response connection

C7:

Sec 1.2 Tree Diagrams

Old text should be replaced with reference to
draft-ietf-netmod-yang-tree-diagrams-01

C8:

 (M1) IETF copyright says 2014; change to 2017
 (M2) IETF copyright says 2014; change to 2017

Nits:

Some descriptions mention SSH. This should be removed from
this document.

The descriptions for choices that have only 1 case should
explain why a choice is being used.

The tree diagram shows the fully expanded groupings,
even many objects are in other drafts. I needed all 5 drafts
open in windows for searching, plus pyang tree output,
to really follow the data model structure.

The examples do not show any usage of the hello-params.
This would be useful because the namespace for the
identityref objects (tls-version, cipher-suite) is not
the same as the module that uses the grouping.

Note that the 'map-type' identityref is shown correctly encoded
in examples on page 19 and 20.