Subject: [Netconf] More restconf-09 comments/questions (edit collision detection and error handling)

From: Robert Wilton <[email-masked]>
Date: Tue, 8 Mar 2016 14:22:01 +0000

Hi,

I've a few more review comments/questions on restconf-09 as I've studied 
it a bit more closely over the last couple of days, particularly 
concerning edit collision detection and error handling.

1. General question:  It looks like all the requests target resources 
without a trailing slash. Should the draft specify what behaviour is 
expected if the server receives a request with a trailing slash (e.g. 
probably redirect back to the version of the resource without a trailing 
slash).  Personally, I think that not specifying this is probably fine - 
but thought it might be worth raising in case it hadn't been considered.

2. Section 3.4 Datastore Resource:
Old:

    Configuration edit transaction management and configuration
    persistence are handled by the server and not controlled by the
    client.  A datastore resource can only be written directly with the
    *PATCH *method.  Each RESTCONF edit of a datastore resource is saved to
    non-volatile storage by the server.

The last paragraph states that a datastore resource can only be written 
directly with the PATCH method.  But section 4.4 indicates that POST is 
also allowed.  Does this text need to be changed to allow for PATCH or POST?

E.g new:

    Configuration edit transaction management and configuration
    persistence are handled by the server and not controlled by the
    client.  A datastore resource can only be written directly with the
    *PATCH **or POST*  methods.  Each RESTCONF edit of a datastore resource is
    saved to non-volatile storage by the server.

3. Section 3.4.1 Edit Collision Detection (applies equally to the 
Timestamp and Entity tag):
3.4.1.1.  Timestamp

    The last change time is maintained and the "Last-Modified"
    ([RFC7232], Section 2.2 <https://tools.ietf.org/html/rfc7232#section-2.2>) header is returned in the response for a
    retrieval request.  The "If-Unmodified-Since" header can be used in
    edit operation requests to cause the server to reject the request if
    the resource has been modified since the specified timestamp.

    The server MUST maintain a last-modified timestamp for the top-level
    {+restconf}/data resource and SHOULD maintain last-modified
    timestamps for descendant resources.  For all resources, the server
    MUST return the "Last-Modified" header when the resource is retrieved
    with the GET or HEAD methods.  If the server does not maintain a
    timestamp for a resource, it MUST return the timestamp of the
    resource's ancestor, a process that may recurse up to the top-level
    {+restconf}/data resource.  Only changes to configuration data
    resources within the datastore affect the timestamp.

  i) Do the timestamp and entity tag appear to apply to both config and 
non config resources, or is it just config resources?
  ii) If it is just config resources then please can sections 3.4.1.1 
and 3.4.1.2 be updated to make this clear.
  iii) If it both config and non config resources, then it is unclear to 
me what the exact semantics for non config resources are expected to 
be?  (Based on the description in section 3.5 - I can elaborate if needs be)

4. Section 3.5 Data Resource.
To be consistent with 3.4.1.1 and 3.4.1.2, I think that the MAY should 
change to SHOULD:

I.e. old:

    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. ...

new:

    For configuration data resources, the server*SHOULD *maintain a last-
    modified timestamp for the resource, and return the "Last-Modified"
    header when it is retrieved with the GET or HEAD methods. ...

Likewise for entity tag:
old:

    For configuration data resources, the server*MAY *maintain a resource
    entity tag for the resource, and return the "ETag" header when it is
    retrieved as the target resource with the GET or HEAD methods.

new:

    For configuration data resources, the server*SHOULD *maintain a resource
    entity tag for the resource, and return the "ETag" header when it is
    retrieved as the target resource with the GET or HEAD methods.

5. Section 3.5 Data Resource, last paragraph.
I didn't understand what the last paragraph means, or what it relevance is:

    The resource definition version for a data resource is identified by
    the revision date of the YANG module containing the YANG definition
    for the data resource.

6. Section 4.1. OPTIONS:

    The OPTIONS method is sent by the client to discover which methods
    are supported by the server for a specific resource (e.g., GET, POST,
    DELETE, etc.).

    The server SHOULD implement this method, however the same information
    could be extracted from the YANG modules and the RESTCONF protocol
    specification.

What body text (if any) should be returned for OPTIONS requests?  If 
body text is returned then what media type should it use?

E.g. RFC 7231, section 4.3.7 "options" indicates that the body might 
contain a human readable description.

7. Section 4.3 GET, first paragraph:

    The GET method is sent by the client to retrieve data and meta-data
    for a resource.  It is supported for all resource types, except
    operation resources.  The request MUST contain a request URI that
    contains at least the entry point.

It isn't clear to me what the last sentence is trying to say - I'm not 
sure exactly what is meant by "entry point".

8. Section 5.1 last but one paragraph.  Should the "MUST" be changed to 
"can"?

old:

    When new resources are created by the client, a "Location" header is
    returned, which identifies the path of the newly created resource.
    The client*MUST *use this exact path identifier to access the resource
    once it has been created.

new:

    When new resources are created by the client, a "Location" header is
    returned, which identifies the path of the newly created resource.
    The client*can *use this exact path identifier to access the resource
    once it has been created.

9. Section 7.1 Error Response message:

    When an error occurs for a request message on a*data *resource or an
    operation resource, and a "4xx" class of status codes (except for
    status code "403 Forbidden"), then the server SHOULD send a response
    message-body containing the information described by the "errors"
    container definition within the YANG moduleSection 8 
<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-8>.  The Content-
    Type of this response message MUST be application/yang.errors (see
    example below).

    The client*MAY *specify the desired encoding for error messages by
    specifying the appropriate media-type in the Accept header.*If no error media is specified, then the media type of the request 
message is used. If there is no request message the server*  MUST select
    "application/yang.errors+xml" or "application/yang.errors+json",
    depending on server preference.  All of the examples in this
    document, except for the one below, assume that XML encoding will be
    returned if there is an error.

i) The beginning of the error paragraph makes the description 
conditional on the request message being on a data resource.  Should 
this cover other resource types as well, or otherwise what is the error 
handling strategy for other resource types?
ii) Should the last sentence of the first paragraph be "Type of this 
response message MUST be a subtype of application/yang.errors (see 
example below). "?
iii) Would it be wise to indicate that the client SHOULD specify desired 
encoding for error messages?
iv) The second paragraph states "If no error media is specified, then 
the media type of the request message is used. " but this directly 
conflicts with "The Content- Type of this response message MUST be 
application/yang.errors (see example below). "
v) "If there is no request message the server ..." - I would think that 
there must always be a request message.

In summary, what about this text instead:

    When an error occurs for a request message on an*api, data,****datastore, or operation resource*, and a "4xx" class of status
    codes (except for status code "403 Forbidden"), then the server
    SHOULD send a response message-body containing the information
    described by the "errors" container definition within the YANG
    moduleSection 8 
<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-8>.  The Content-Type of this response message MUST
    be*a subtype*  of application/yang.errors (see example below).

    The client*SHOULD *specify the desired encoding for error messages by
    specifying the appropriate media-type in the Accept header.*If no error media-type is specified, then the server SHOULD choose an****error media-type encoding (XML or JSON) that is consistent to what would 
have**been used if the request succeeded. If the client did not specify**any particular media type in the Accept header then the server*  MUST
    select "application/yang.errors+xml" or "application/yang.errors+json",
    depending on server preference.  All of the examples in this
    document, except for the one below, assume that XML encoding will be
    returned if there is an error.

Thanks,
Rob

---

From: Robert Wilton <[email-masked]>
Date: Mon, 14 Mar 2016 10:26:10 +0000

To add to the question/comments below, I have some more 
questions/comments on query parameter handling:

These questions related to section 4.8: Query Parameters
1. Are query parameters and paths case sensitive?  I would guess so.  
The draft doesn't make any explicit mention of this, but perhaps this is 
covered by the HTTP 1.1 draft.

2. Should an unexpected query parameter cause an error or should it just 
be ignored?  For some (but not all) of the query parameters in sections 
4.8.1 through 4.8.9 it indicates that an explicit error should be 
returned if the query parameter is used for an unsupported resource 
type, but section 4.8 allows vendor specific query parameters to also be 
defined.  Should these also cause errors if they are not known?

3. Both the depth and fields query parameters (4.8.2 & 4.8.3) indicate 
that they apply to the API resource (3.3), but I wasn't sure that they 
served any purpose since my reading of the draft is that the api 
resource is just the top level and effectively fixed. I.e. it doesn't 
return any data from the datastore or the operations, and they need to 
be explicitly queried separately if required.

4. Minor nit.  It might be helpful if the options were listed in the 
same order as they are listed in the table in section 4.8.  E.g. this 
would mean that the section on filter would need to move up above the 
section on insert.

5. Section 4.8.2: The "depth" Query Parameter
The last but one paragraph reads:

    "By default, the server will include all sub-resources within a
    retrieved resource, which have the same resource type as the
    requested resource.  Only one level of sub-resources with a different
    media type than the target resource will be returned."

I'm not quite sure what the purpose of this paragraph is.  Would this 
mean that that a GET request on /restconf/data is only expected the 
first layer of children nodes?

6. Section 8: "error-info". Should the type be anydata rather than the 
deprecated anyxml?

Rob

On 08/03/2016 14:22, Robert Wilton wrote:
> Hi,
>
> I've a few more review comments/questions on restconf-09 as I've 
> studied it a bit more closely over the last couple of days, 
> particularly concerning edit collision detection and error handling.
>
>
> probably redirect back to the version of the resource without a 
> trailing slash).  Personally, I think that not specifying this is 
> probably fine - but thought it might be worth raising in case it 
> hadn't been considered.
>
>
> The last paragraph states that a datastore resource can only be 
> written directly with the PATCH method.  But section 4.4 indicates 
> that POST is also allowed.  Does this text need to be changed to allow 
> for PATCH or POST?
>
> E.g new:
>  iii) If it both config and non config resources, then it is unclear 
> to me what the exact semantics for non config resources are expected 
> to be?  (Based on the description in section 3.5 - I can elaborate if 
> needs be)
>
>
> 8. Section 5.1 last but one paragraph.  Should the "MUST" be changed 
> to "can"?
>
> old:
> this cover other resource types as well, or otherwise what is the 
> error handling strategy for other resource types?
> iii) Would it be wise to indicate that the client SHOULD specify 
> desired encoding for error messages?
> v) "If there is no request message the server ..." - I would think 
> that there must always be a request message.
>
>     specifying the appropriate media-type in the Accept header.*If no error media-type is specified, then the server SHOULD choose an****error media-type encoding (XML or JSON) that is consistent to what 
> would have**been used if the request succeeded. If the client did not specify**any particular media type in the Accept header then the server*  MUST
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf