Subject: Re: [weirds] Working Group Last Call: draft-ietf-weirds-using-http

From: Alexander Mayrhofer <[email-masked]>
Date: Thu, 28 Mar 2013 12:32:48 +0000

I've taken the opportunity of the WGLC to perform a review of the using-http draft (i haven't followed all discussions during the development of this draft, so some of my points might have been discussed before, or are too late in the process):

- Title: If i would start the document, i would have called it "HTTP usage in RDAP" instead of the other way around [might be personal taste, though]
- Abstract: "usage" and "using" in the same sentence sounds weird(s) to me [but English is not my first language]

- Introduction: Would change first sentence into "... describes the RESTful usage of HTTP .... running on web servers...", since i the RESTfulness is imho a property of the HTTP usage, rather then the HTTP server (as the technical contraption that's being used for RESTful usage).

- Intorduction: The last paragraph would probably fit better before the "basic usage pattern" bullet list?

- Introduction, 3rd bullet point: use "HTTP(s) URL" instead of "HTTP URL"?

- Introduction: Additional  bullet point that servers can refuse queries for policy reasons with response code out of the 4xx range (eg. 403, 429)

- Section 4.1: I understand that clients not designating themselves as "RDAP clients" may still send Accept: headers - correct?

- Section 4.2: Add text about *known* query parameters, since the Section title says "Query Parameters" in general? Eg. that they are defined in the respective protocol-level document... Implementors need to understand how to identify the set of "unknown" parameters.

- Section 5: The "Negative Answer" section only describes the case where the server has no information about the query. However, there's no text about the case where the server wishes to respond that it *has* the requested information, but cannot return it due to server policy for the specific client (for example, that [additional] authentication is required in order to retrieve the information - or the client ip range has been blocked because if misuse of the service). This case does neither fit the "positive answer" definition, nor the "negative answer". Therefore, i think that either the "Negative Answer" section should be extended, or a seperate section ("Policy prohibits answer"?) should be added, with text such as

If a server wishes to inform the client that information about the query is available, but cannot include the information in the response to the client for policy reasons, the server SHOULD respond with an adequate response code out of HTTP's 4xx range. Clients MAY retry the query based on the respective response code.

(I'm trying to say that servers may request authenication [401], might refuse a client completely [403], ... hmm.. what about 402... ;-) 410 could also be useful in certain scenarios, particularly with entities where identifiers are not re-used)

What's hard to cover is the case where basic information is available with no authentication, but additional information (such as full entity address information) would be availabe if the client authenticated. Worse, even, if the authentication scheme was not HTTP-based (but, for example, based on client certificates, or cookies)..

- The security considerations section is missing.

- Section 8.1: I do understand that this does not prevent RDAP to use percent-encoded non-ASCII characters in URIs, correct?

- Section 8.3: I'm a bit unsure whether the SHOULD in this section violates RFC2616? Specifically, RFC2616 says " If an  Accept-Language header is present, then all languages which are  assigned a quality factor greater than 0 are acceptable." To me, this says that an Accept-Language header can't be ignored, because languages not listed are not acceptable? (I understand that in practice, it might be desireable to ignore the header - but it would by tricky for the document to contradict an RFC that is references as normative...

- Section 8.3: What about Accept-Encoding and Accept-Charset, which are related to Accept-Language?

tia,

Alex Mayrhofer
Head of R&D nic.at

---

From: Andy Newton <[email-masked]>
Date: Thu, 28 Mar 2013 19:13:36 +0000

Alexander,

My responses are in-line:

On 3/28/13 8:32 AM, "Alexander Mayrhofer" <[email-masked]>
wrote:

>- Title: If i would start the document, i would have called it "HTTP
>usage in RDAP" instead of the other way around [might be personal taste,
>though]
>- Abstract: "usage" and "using" in the same sentence sounds weird(s) to
>me [but English is not my first language]

The title change works, and I'll work on the abstract.

>
>- Introduction: Would change first sentence into "... describes the
>RESTful usage of HTTP .... running on web servers...", since i the
>RESTfulness is imho a property of the HTTP usage, rather then the HTTP
>server (as the technical contraption that's being used for RESTful usage).
>
>- Introduction: Additional  bullet point that servers can refuse queries
>for policy reasons with response code out of the 4xx range (eg. 403, 429)

All of these make sense.

>
>- Section 4.1: I understand that clients not designating themselves as
>"RDAP clients" may still send Accept: headers - correct?

That is correct. The intent is that one of the URLs could be plugged into
a web browser, which probably defaults to asking for HTML, and that the
server could respond appropriately.

>- Section 4.2: Add text about *known* query parameters, since the Section
>title says "Query Parameters" in general? Eg. that they are defined in
>the respective protocol-level document... Implementors need to understand
>how to identify the set of "unknown" parameters.

I think this is a code point.

>- Section 5: The "Negative Answer" section only describes the case where
>the server has no information about the query. However, there's no text
>about the case where the server wishes to respond that it *has* the
>requested information, but cannot return it due to server policy for the
>specific client (for example, that [additional] authentication is
>required in order to retrieve the information - or the client ip range
>has been blocked because if misuse of the service). This case does
>neither fit the "positive answer" definition, nor the "negative answer".
>Therefore, i think that either the "Negative Answer" section should be
>extended, or a seperate section ("Policy prohibits answer"?) should be
>added, with text such as
>
>If a server wishes to inform the client that information about the query
>is available, but cannot include the information in the response to the
>client for policy reasons, the server SHOULD respond with an adequate
>response code out of HTTP's 4xx range. Clients MAY retry the query based
>on the respective response code.
>
>(I'm trying to say that servers may request authenication [401], might
>refuse a client completely [403], ... hmm.. what about 402... ;-) 410
>could also be useful in certain scenarios, particularly with entities
>where identifiers are not re-used)
>
>What's hard to cover is the case where basic information is available
>with no authentication, but additional information (such as full entity
>address information) would be availabe if the client authenticated.
>Worse, even, if the authentication scheme was not HTTP-based (but, for
>example, based on client certificates, or cookies)..

I think this makes sense. Thanks for the text.

>- The security considerations section is missing.

Jean-Philippe has suggested text for that. Please see his email.

>- Section 8.1: I do understand that this does not prevent RDAP to use
>percent-encoded non-ASCII characters in URIs, correct?

Correct.

>
>- Section 8.3: I'm a bit unsure whether the SHOULD in this section
>violates RFC2616? Specifically, RFC2616 says " If an  Accept-Language
>header is present, then all languages which are  assigned a quality
>factor greater than 0 are acceptable." To me, this says that an
>Accept-Language header can't be ignored, because languages not listed are
>not acceptable? (I understand that in practice, it might be desireable to
>ignore the header - but it would by tricky for the document to contradict
>an RFC that is references as normative...

That last sentence should probably be changed from "when formulating
response" to "when formulating HTTP entity responses". This section says
that the Accept-Language header does not influence the JSON responses.
This was the decision of the working group following the meeting in
Atlanta.

>related to Accept-Language?

I'm torn between the need to say anything about these or not. Servers are
free to support any encoding/charset so long as the support UTF-8 with our
JSON responses. What would you suggest.

-andy

---

From: Alexander Mayrhofer <[email-masked]>
Date: Thu, 28 Mar 2013 19:56:22 +0000

Andy,

thanks for the quick feedback. Please take my comments as suggestions rather than blocking issues (didn't clarify that). Comments on some points inline:

[...]

> >Accept-Language header can't be ignored, because languages not listed
> >are not acceptable? (I understand that in practice, it might be
> >desireable to ignore the header - but it would by tricky for the
> >document to contradict an RFC that is references as normative...
> 
> This was the decision of the working group following the meeting in Atlanta.

[Alexander Mayrhofer] 
Ok, fine with me if that was the decision of the WG - honestly, i didn't even read the minutes - sorry!

> JSON responses. What would you suggest.

[Alexander Mayrhofer] 
Well, obviously the Accept-Language has more of a "user-visible" implication on the presentation of the content, while the Encoding and Charset negotiation happens mostly behind the scenes - therefore i guess that most people focus on the Language negotiation only.

I'm fine with not saying anything about Encoding and Charset, if the authors (and WGs) accept that this means the normal negotiation mechanisms of HTTP apply. 

thanks,

Alex

---

From: Andy Newton <[email-masked]>
Date: Thu, 28 Mar 2013 21:28:05 +0000

On 3/28/13 3:56 PM, "Alexander Mayrhofer" <[email-masked]>
wrote:
>
>[Alexander Mayrhofer]
>Well, obviously the Accept-Language has more of a "user-visible"
>implication on the presentation of the content, while the Encoding and
>Charset negotiation happens mostly behind the scenes - therefore i guess
>that most people focus on the Language negotiation only.
>
>I'm fine with not saying anything about Encoding and Charset, if the
>authors (and WGs) accept that this means the normal negotiation
>mechanisms of HTTP apply.

In my opinion that's what it means. But other feedback would be helpful.

Thanks Alexander.

-andy

---

From: Pieter Vandepitte <[email-masked]>
Date: Thu, 28 Mar 2013 22:43:39 +0100

Hi,

First of all, to all people actively involved in this working draft: congratulations! 

All my remarks are rather small, are more or less a matter of taste and don't contribute to the fundamental stuff of the working draft.

That being said, here are my remarks and comments

> - Title: If i would start the document, i would have called it "HTTP usage in RDAP" instead of the other way around [might be personal taste, though]

IMHO the current title fits best, but that's a matter of taste as you suggested. My personal favourite for example is "HTTP Binding for RDAP"

> - Abstract: "usage" and "using" in the same sentence sounds weird(s) to me [but English is not my first language]

Agree, suggestions for a better abstract? Based on my favourite title, I would suggest: "This document describes a HTTP binding for the RDAP protocol"  (but that doesn't add much value to my proposed title)

> - Introduction: Would change first sentence into "... describes the RESTful usage of HTTP .... running on web servers...", since i the RESTfulness is imho a property of the HTTP usage, rather then…

… describes a RESTful API over HTTP. [period] 'Web servers' is redundant to me (I like short and clear protocols without too much clutter)

> - Introduction, 3rd bullet point: use "HTTP(s) URL" instead of "HTTP URL"?

What about: URL instead of HTTP URL. I would not restrict the scheme to http or https. Suppose next week there's a new standard  HTTPVS ( very secure ) then this RFC is outdated. Or suppose a new RDAP binding is being developed (e.g. RDAP over FTP), one could redirect to an FTP URL (I don't think there's a restriction on scheme for the location header)
> - Introduction: Additional  bullet point that servers can refuse queries for policy reasons with response code out of the 4xx range (eg. 403, 429)

+1

> - Section 8.3: What about Accept-Encoding and Accept-Charset, which are related to Accept-Language?

Agree on all of this

5.2. Redirects

There are several redirect http response codes: 301, 302, 307 and 308. The last two are more or less the equivalents of the first two, except that they do not allow the the client to change the request method (could be important if there would be POST, PUT,… RDAP methods in the future)

The sentence "In other words, when generating the redirect url, the server will  only alter the base of the URL.  It will not attempt to normalize or modify the path segment."
=> Shouldn't that be: "The path segment of the URL MAY be appended with a redirect info if none is provided or MUST be altered to reflect the redirect status in case the URL contains redirect info as specified in draft-ietf-weirds-redirects" ? 

5.3 Negative Answers

I only recently followed the list, but I can imagine there have been long debates about MUST, SHOULD, ….: "it SHOULD return a 404 response code" => SHOULDn't that be a MUST? Or do situations exist where a server can ignore this recommendation and do it's own thing?

same for 5.4

8.2.  Language Identifiers in Queries and Responses
What do we mean with "the data should be annotated with language identifiers"? HTTP response headers like Content-Language and Content-Type (with its charset parameter)? Shouldn't we mention them? And aren't 8.2 and 8.3 strongly related and shouldn't these two sections be merged?

Additional remarks:

* What about the recent discussion on Search documents. i.e. searching and returning multiple results: then the first design intent ( 3. Design Intents) doesn't hold anymore. Can't we relax this statement?
* The link to http://www.w3.org/TR/2012/WD-cors-20130129 doesn't work. http://www.w3.org/TR/2013/CR-cors-20130129/ or http://www.w3.org/TR/cors/ (but dangerous to link to the latest version i suppose)

kr,

Pieter

---

From: Andy Newton <[email-masked]>
Date: Fri, 29 Mar 2013 16:20:39 +0000

On 3/28/13 5:43 PM, "Pieter Vandepitte" <[email-masked]> wrote:

>* What about the recent discussion on Search documents. i.e. searching
>and returning multiple results: then the first design intent ( 3. Design
>Intents) doesn't hold anymore. Can't we relax this statement?

That should probably be changed to mean HTTP entities instead of results.

>* The link to http://www.w3.org/TR/2012/WD-cors-20130129 doesn't
>work.http://www.w3.org/TR/2013/CR-cors-20130129/ or
>http://www.w3.org/TR/cors/ (but dangerous to link to the latest version i
>suppose)

Thanks.

-andy