Review of draft-ietf-netconf-restconf

[mnot]

I'm not sure this is the most appropriate way to give feedback, but it's the easiest :)

Some things I noticed in a reading -13:

• In Terms, there are a few "resources" that are defined as "a resource with the media type...". It would be more accurate to say "a resource that has a representation with the media type..." (because resources don't have media types in HTTP).
• "plain patch" is defined as "a specific PATCH request type that can be used for simple merge operations." What media type does it have, if it's specific? A link to the defining section would help.

• This strategy obviates the need for responses provided by the server to contain Hypermedia as the Engine of Application State (HATES) links, originally described in Roy Fielding's doctoral dissertation [rest-dissertation].

  I'd say this differently; AIUI the client is able to use the data presented by NETCONF to determine the links it needs.

• HTTP/1.1 pipelining MUST be supported by the server. Responses MUST be sent in the same order that requests are received.

  It's not appropriate to re-state requirements from HTTP; if it's a HTTP/1.1 server, it will support pipelining. Also, see below RE: versions.

• No other versions of HTTP are supported for use with RESTCONF.

  As noted elsewhere, this seems needlessly restrictive, and probably impossible to enforce. HTTP versioning is hop-by-hop, so a client behind a proxy can't control the version of HTTP presented to the server, and vice versa.

• If the RESTCONF client is not authorised to access a resource, the server MUST send an HTTP response with "401 Unauthorised" status-line

  401 is used for authentication challenges, not authorisation. It might equally be appropriate to present 403 Forbidden (especially if client cert authentication is in use, since it doesn't (currently) use 401). Also, there are situations where this MUST can be reasonably violated, e.g., if a 400, 500, 501, etc. status code is more appropriate; it needs to be a SHOULD.

• A resource has a media type identifier, represented by the "Content-Type" header in the HTTP response message.

  As elsewhere, resources don't have media types.

• In a few examples, Server example.com -- missing colon
• ETag: a74eefc993a2b -- missing quotes around the etag-value
• Same example - Pragma is a request header field, it is not valid in responses.

• Note that the way that access control is applied to data resources is completely incompatible with HTTP caching. The Last-Modified and ETag headers maintained for a data resource are not affected by changes to the access control rules for that data resource. It is possible for the representation of a data resource that is visible to a particular client to be changed without detection via the Last- Modified or ETag values.

  It's not "completely incompatible"; as described below that passage, responses can be cached, but need to be validated before being used to satisfy a request (i.e., Cache-Control: no-cache semantics). I also strongly suspect you could assign a freshness lifetime if appropriate Vary or Key headers are sent.

• The DELETE method is used to delete the target resource. If the DELETE request succeeds, a "204 No Content" status-line is returned, and there is no response message-body.

  Other users of these resources might find a response body helpful (e.g., negotiated by Prefer); it shouldn't be prohibited (while there's no 2119 language here, some might interpret it as such). Also, "there is no response message-body" is true for 204, it's best to leave the definition of what does and does not have a message body to RFC7230 (as this is an area rife with bugs and interop problems).

• query: the set of parameters associated with the RESTCONF message. These have the familiar form of "name=value" pairs.

  This is very informal; the syntax you're referring to is defined by HTML5, not HTTP or URIs, so you need to refer to that spec.

• fragment: This field is not used by the RESTCONF protocol.

  It would be good if the media types clearly specify their fragment identifier semantics where possible, so that future uses can leverage them, even if this protocol doesn't use them.

• Since the datastore contents change at unpredictable times, responses from a RESTCONF server generally SHOULD NOT be cached.

  See above re: caching.

• A "Pragma" header specifying "no-cache" MAY also be sent in case the "Cache-Control" header is not supported.

  See above re: appropriate use of Pragma.

• Instead of relying on HTTP caching, the client SHOULD track the "ETag" and/or "Last-Modified" headers returned by the server for the datastore resource (or data resource if the server supports it).

• HTTP status-lines are used to report success or failure for RESTCONF operations.

  Status codes, not status lines. The status line includes the reason phrase, which is not guaranteed to persist end-to-end.

• The following table summarizes the return status codes used specifically by RESTCONF operations

  This table makes me really uncomfortable; it will be read by many as redefining / specialising the semantics of HTTP status codes.

• The parent MIME media type for RESTCONF resources is application/yang, which is defined in [RFC6020]. Has this use of the "." syntax been discussed with the media types community? To date, that's been used only to indicate a registration tree, which this is not.
• The structure of the document makes it hard to find the definitions of the individual link relation types' semantics (reflected by the resources they identify), and the syntax and semantics of the media types defined. These are first-class artefacts in HTTP-based protocols.
• It's a bit of a pity that host-meta is just used to discover the entry point; it could have been used to discover more of the API's resources (or templates for them), allow more flexibility in deployment, and the ability to layer in new resources without versioning the whole protocol.
• Finally, "RESTCONF" is a horrible name; is it too late to change it to "NETCONF-HTTP"?

[abierman]

Same example - Pragma is a request header field, it is not valid in responses.

https://tools.ietf.org/html/rfc7234#section-5.4

[abierman]

Finally, "RESTCONF" is a horrible name; is it too late to change it to "NETCONF-HTTP"?

RESTCONF is not state-full or session-based like NETCONF. The RESTCONF term has already stuck. We tried YANG-API at first and tried to avoid RESTCONF but people insisted on changing it to RESTCONF

[mnot]

It's a horrible name because REST has become quite a muddied term, and this use further muddies it. REST is an architectural style, whereas what you're doing is a very specific protocol built on top of HTTP.

Given that the standard has not been approved by the IESG, I don't see how it can have "stuck" -- while the set of people working on it now and using early implementations might be familiar with it, the set of people involved if it succeeds as a standard will be much larger.

Ping @royfielding for any thoughts he'd like to add.

[abierman]

fixed in draft -15 media types will have -xml added in draft 16