Subject: [Netconf] Opinion poll on RESTCONF encoding

From: Mahesh Jethanandani <[email-masked]>
Date: Wed, 26 Aug 2015 17:03:57 -0700

A little more than two weeks ago, the chairs of NETCONF WG had issued a opinion poll on RESCONF encoding. The options given were:

x) XML is mandatory, JSON optional,
j) JSON is mandatory, XML optional,
x&j) XML and JSON are both mandatory,
x+j) Either XML or JSON is mandatory the other one is optional,
nm) Both XML and JSON are optional and _not_ mandatory.

The option x+j won by a large margin and at this time can be declared as the rough consensus by the WG.

Separately, a secondary question was raised around how the encoding could be or would be discovered. On that we do not seem to have a consensus. Two proposals that were made are:

Client sends all supported encodings in Accept request-header, with an (optional) preference indication via quality (q). Server responds with one of the encodings or 406 (not supported). The encoding formats would be limited to a small set - XML and JSON with this option to encourage interoperability.
Server advertises support of encodings using the ./well-known/host-meta file and XRD.

Please indicate your opinion on the discovery of encoding part of the discussion. This opinion will not change the consensus on the poll of RESTCONF encoding.

Mahesh & Mehmet

---

From: Andy Bierman <[email-masked]>
Date: Wed, 26 Aug 2015 17:23:27 -0700

On Wed, Aug 26, 2015 at 5:03 PM, Mahesh Jethanandani <
[email-masked]> wrote:

> A little more than two weeks ago, the chairs of NETCONF WG had issued a
> opinion poll on RESCONF encoding. The options given were:
>
> Separately, a secondary question was raised around how the encoding could
> be or would be discovered. On that we do not seem to have a consensus. Two
> proposals that were made are:
>
>
>    1. Client sends all supported encodings in Accept request-header, with
>    an (optional) preference indication via quality (q). Server responds with
>    one of the encodings or 406 (not supported). The encoding formats would be
>    limited to a small set - XML and JSON with this option to encourage
>    interoperability.
>    2. Server advertises support of encodings using the
>    ./well-known/host-meta file and XRD.
>
>
> Please indicate your opinion on the discovery of encoding part of the
> discussion. This opinion will not change the consensus on the poll of
> RESTCONF encoding.
>
>
This really isn't subject to the opinion of the WG.
HTTP uses the Accept header.
The only issue for RESTCONF is what does the server do if
there is no Accept header from the client?
Currently I think the draft says the server will send XML by default.
It needs to change to be silent and let the server send whatever it wants.

Even if (2) was done the server still MUST support the Accept header.

> Mahesh & Mehmet
Andy

>
>
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>
>

---

From: Kent Watsen <[email-masked]>
Date: Thu, 27 Aug 2015 01:37:30 +0000

1.  Client sends all supported encodings in Accept request-header, with an (optional) preference indication via quality (q). Server responds with one of the encodings or 406 (not supported). The encoding formats would be limited to a small set - XML and JSON with this option to encourage interoperability.
  2.  Server advertises support of encodings using the ./well-known/host-meta file and XRD.

We have to do #1.   Proposal #2 is a bonus...one that I'm OK with deferring until after we have more operational experience with RESTCONF.

To recap, #2 was to enable the server to proactively state what it supports, but it only works if encodings are universal, never varying between resources.    Making the most of #1, RESTCONF could state in Section 5.3:

  If no Accept header is present, or if none of the passed Accept
  header media types are supported for the given resource, the
  RESTCONF server MUST generate a payload containing a list of
  available representation characteristics and corresponding
  resource identifiers from which the user or user agent can
  choose the one most appropriate.

This is slightly stricter than the wording in RFC 7231, Section 6.5.6.

My opinion is that, if the client is willing to accept any encoding, it should passed "*/*" as one of the values in its Accept header.  Note, testing 5 browsers just now, they all passed "*/*" in a random GET request.  This is important because we likely want to support this common developer action and have the server respond with something reasonable.

Kent

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 27 Aug 2015 07:26:49 +0200

> This is slightly stricter than the wording in RFC 7231, Section 6.5.6.

-1 (since I do not think this is how HTTP generally works)

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 27 Aug 2015 12:40:32 +0200

> Even if (2) was done the server still MUST support the Accept header.

I agree with Andy, this is really HTTP business, and RESTCONF is just an
application on top of it.

Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 27 Aug 2015 12:46:08 +0200 (CEST)

> application on top of it.

I agree that we should not specify anything about the Accept header;
that is HTTP's business.

But this doesn't mean that (2) cannot be useful.  With (2) a client
can learn the encodings supported by the server before it constructs
payload in an encoding that may or may not be supported by the server.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 27 Aug 2015 13:03:08 +0200

> On 27 Aug 2015, at 03:37, Kent Watsen <[email-masked]> wrote:
> 
> 
>> 	• Client sends all supported encodings in Accept request-header, with an (optional) preference indication via quality (q). Server responds with one of the encodings or 406 (not supported). The encoding formats would be limited to a small set - XML and JSON with this option to encourage interoperability.
>> 	• Server advertises support of encodings using the ./well-known/host-meta file and XRD.
>> 

RFC 7231 also says: “A request without any Accept header field implies that the user agent will accept any media type in response.” We should not change HTTP semantics.

Lada

---

From: Kent Watsen <[email-masked]>
Date: Thu, 27 Aug 2015 15:43:11 +0000

>-1 (since I do not think this is how HTTP generally works)

Which part?  - how to handle the case when no Accept header is passed, how
to handle when no passed Accept type is supported, or the s/SHOULD/MUST/?

Kent

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 27 Aug 2015 18:12:21 +0200

> to handle when no passed Accept type is supported, or the s/SHOULD/MUST/?

It does not matter, we should not change HTTP. This is what RRC 7231
has to say:

   A request without any Accept header field implies that the user agent
   will accept any media type in response.

   [...] If the header field is
   present in a request and none of the available representations for
   the response have a media type that is listed as acceptable, the
   origin server can either honor the header field by sending a 406 (Not
   Acceptable) response or disregard the header field by treating the
   response as if it is not subject to content negotiation.

I also think the notion of "available representation characteristics
and corresponding resource identifiers" is likely misleading since it
seems to say that different representations can have different
resource identifiers (i.e., they are are different resources).

Apparently, I have multiple reasons for a -1.

/js

---

From: Kent Watsen <[email-masked]>
Date: Thu, 27 Aug 2015 17:31:31 +0000

>It does not matter, we should not change HTTP.

But we're not, HTTP has a bunch of "SHOULD"s that can and should be
restricted as it makes sense for REST APIs.   Please feel free to search
REST API best practices on this.

> This is what RRC 7231 has to say:
>

Lada brought this up too.   Yes, this could be interpreted as "assume */*
was passed" or, per section 3.4.2:

   A server might choose not to send an initial representation, other
   than the list of alternatives, and thereby indicate that reactive
   negotiation by the user agent is preferred.  For example, the
   alternatives listed in responses with the 300 (Multiple Choices) and
   406 (Not Acceptable) status codes include information about the
   available representations so that the user or user agent can react by
   making a selection.

BTW, I tested `wget` and `curl` also, they both pass "*/*" like the
mainline browsers...

Kent

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 27 Aug 2015 17:45:17 -0700

What I am reading from the discussion till now is:

Accept request-header needs to be supported and that it is not an option.
The client can choose not to send the header, in which case the server can pick an encoding of its choice and respond with it.
The client can send what it does support, in which case the server either accepts the encoding it supports or returns a 406. The 406 (Not Acceptable) status codes include information about the available representations.
The client can send “*/*". Same behavior as not getting a Accept header.
Server MAY support advertising of encodings using the ./well-known/host-meta file and XRD.

If this a fair summary, we can update the RESTCONF draft with these details.

> On Aug 27, 2015, at 10:31 AM, Kent Watsen <[email-masked]> wrote:
> 
> 
> 
> 

Mahesh Jethanandani
[email-masked]

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 28 Aug 2015 09:22:41 +0200

> On 28 Aug 2015, at 02:45, Mahesh Jethanandani <[email-masked]> wrote:
> 
> 	• Accept request-header needs to be supported and that it is not an option.
> 	• The client can choose not to send the header, in which case the server can pick an encoding of its choice and respond with it.
> 	• The client can send what it does support, in which case the server either accepts the encoding it supports or returns a 406. The 406 (Not Acceptable) status codes include information about the available representations.
> 	• The client can send “*/*". Same behavior as not getting a Accept header.
> 	• Server MAY support advertising of encodings using the ./well-known/host-meta file and XRD.

+1

Lada

---

From: Kent Watsen <[email-masked]>
Date: Fri, 28 Aug 2015 20:40:29 +0000

>> 	€ Accept request-header needs to be supported and that it is not an
>>option.
>> 	€ The client can choose not to send the header, in which case the
>>server can pick an encoding of its choice and respond with it.
>> 	€ The client can send what it does support, in which case the server
>>either accepts the encoding it supports or returns a 406. The 406 (Not
>>Acceptable) status codes include information about the available
>>representations.
>> 	€ The client can send ³*/*". Same behavior as not getting a Accept
>>header.
>> 	€ Server MAY support advertising of encodings using the

+1 (and we should decide if the 406 response format is text or something
else)

>> 
>> If this a fair summary, we can update the RESTCONF draft with these
>>details

Right, Section 5.3 needs to be rewritten.

Kent