Subject: Re: [apps-discuss] Applications Area Directorate Review of draft-ietf-weirds-using-http-07

From: Olaf Kolkman <[email-masked]>
Date: Sun, 11 Aug 2013 13:33:58 +0200

Thanks Larry,

[ Adding the WG, for transparency purposes. ]

In my role of doc-shepherd I've put some comments in-line. Overall I am trying to tease out the actionable bits and try to suggest some resolutions. I leave it to the document editors to come up with concrete text.

It is clear to me that addressing Larry's comments will lead to a better context which will help future implementors. Thanks for that Larry.

On Jul 31, 2013, at 2:19 PM, Larry Masinter <[email-masked]> wrote:

> I have been selected as the Applications Area Directorate reviewer for this draft (for background on appsdir, please see ​http://trac.tools.ietf.org/area/app/trac/wiki/ApplicationsAreaDirectorate ).
> 
> Please resolve these comments along with any other Last Call comments you may receive. Please wait for direction from your document shepherd or AD before posting a new version of the draft.
> 
> Document: draft-ietf-weirds-using-http-07
> Title:  HTTP usage in the Registration Data Access Protocol (RDAP)
> Reviewer: Larry Masinter	
> Review Date: 7/31/2013
> IETF Last Call Date: [include if known]
> IESG Telechat Date:  On agenda of 2013-08-15 IESG telechat
> Summary:  The document needs quite a bit of editorial work, but the protocol itself seems OK, modulo a few questions.
> 
> Major Issues/Minor issues:   I think the document suffers enough editorial confusion that they rise to the level of "Major"
> 
> Please define what "Registration Data" is on first use.
> Please define what "Registration Data Directory Services" are.
> Please supply a reference for "RESTful"
> 
> Please explain what you mean by "better" in:
>   "By giving the various Directory Services common
>    behavior, a single client is better able to retrieve data from
>    Directory Services adhering to this behavior."
> Better how?
> 
> Please explain or give an example about what is insufficient in:
>    "the WHOIS protocol is insufficient to
>    modern registration data service requirements."
> 
> 
> The sentence
> ” Where complexity may reside, it is the goal of this document..."
> is awkward, suggest just striking "Where complexity may
> reside".
> 
> 
> Please explain who "SSAC" is and why their opinion about WHOIS is relevant.
> in " As is noted in SSAC Report ..."
> 
> Please give a reference for RDAP
> 

This whole set of comments suggest that for somebody not active in the Internet Registry world this work falls out of thin air. At IETF last call Subremanian Moonesamy had similar comments. I believe your suggestions for expansions would go a long way fixing that.

> 
> Section 2 Terminology:
> "   In this document, an RDAP client is an HTTP User Agent performing an
>    RDAP query, and an RDAP server is an HTTP server providing an RDAP
>    response.  RDAP query and response formats are described in other
>    documents in the collection of RDAP specifications, while this
>    document describes how RDAP clients and servers use HTTP to exchange
>    queries and responses."
> 
> I  think you're defining a way of layering RDAP-like functionality using
> HTTP instead of something lower level.  This doesn't seem like "terminology" --
> this document defines a kind of RDAP client and a kind of RDAP server.

Action: Change of header ?

> 
> Section 3 "Design Intents"
> 
> Neither "design intents" or "design ctriteria" seems to fit
> what you're talking about. "Design constraints"? "Design
> considerations" ? Notable "design decisions" ?
> 
> I don't understand whether restricting responses to zero or one
> result is a difficult or onerous constraint.
> 

Suggested action: Change the first sentence to:
"In this document made a number of design choices are made" 

> "First, each query is meant ..." Each RDAP query itself? In all RDAP
> applications ever? If not, in what circumstances? Which RDAP
> queries have this constraint?
> 

I believe this to be Each RDAP query by all RDAP applications ever. If that is a misunderstanding (and the working-group will no-doubt correct me if I misunderstand) then we probably need clarifying text .

> Is it the "semantics" of the "request/response" that allows
> for future response formats? I think you're saying something
> about the protocol being extensible in the future to allow
> other formats than JSON.
> 

Correct. Would adding something like "i.e. the protocol is extendable to allow other formats than JSON" help to clarify?

> Moving "including cache control, authorization, compression, and
> redirection" to after "HTTP offers a number of mechanisms" (surrounded by
> parentheses) will make the sentence clearer. 

Clear action.

> 
> However, I'm not convinced that you can avoid giving more
> specific advice about how cache control, authorization, 
> compression and redirection work with RDAP.  For example,
> the cache-busting section indicates that cache control headers
> aren't sufficient.
> 
> How will RDAP over HTTP work on a hotel network which redirects HTTP
> requests each day at noon?

I do not recall this to be discussed in detail in the WG.  Are there references for generic approaches to these sort of problems? 
Also, how specific does this need to be given that the protocol serves a specify use case with specific users (producers and clients of Internet Registry data that is currently published in WHOIS databases).

The actions are either "don't be more specific", add a reference, or add text. 

> 
> " an RDAP specific JSON media
>   type, the generic JSON media type, or both."
> 
> Please be explicit  "application/json" for "the generic JSON media type"
> and give an explicit example of  "an RDAP specific JSON media type"
> and provide references where those are defined.

Those seem very clear suggestions for resolution, thanks.
Action: Editorial clarification.

> 
> 5.1 Positive Answers
> 
> can you be more explicit about what kind of response is expected?

Would it be sufficient to refer to the fact that a JSON object will be returned?

> 
> Please address the use of HTTPS with TLS vs. HTTP.

Would a reference to http://tools.ietf.org/html/draft-ietf-weirds-rdap-sec suffice?

> 
> I question the use of 404 Not Found to indicate "no information
> regarding the query", since it doesn't distinguish between "no information"
> and "wrong query".

Not sure what you mean with 'wrong query'.
If you mean  "Malformed Query"  then that is addressed by section 5.4. 
If you mean "No business asking" then that is addressed in the last paragraph of 5.3.

> 
> Please be more explicit about "a RDAP-HTTP Server" rather than
> "a server" in 5.3, 5.4 etc.
> 

Clear action.

> " Optionally, it MAY
>   include additional information regarding the negative answer in the
>   HTTP entity body."
> how can this be used interoperably with such little specified?
> 
> I admit I am baffled by the Extensibility section 6, since I can't see
> how it allows extensions.... for what? Under what cicumstances?
> How do you distinguish between known and unknown extensions?
> 
> Section 7: Security Considerations
> Normally, a security considerations section might outline threats
> and mitigations for them. This section doesn't seem to.

I think this is also where we see that the specifications are a bit targeted to a specific audience of Internet Registry producers and clients.

I am of the impression that the WG wants to keep the mesh of normative cross references to other documents to a minimum. but maybe a reference to http://tools.ietf.org/html/draft-ietf-weirds-rdap-sec would help here to?

> 
> Section 9.1 URIs and IRIs
> This is confusing, of course clients can use whatever internally
> they want.   
> 
> How is a "URI" used in a response? The response is RDAP information.

e.g. in redirects.

> 
> Transforming URIs to IRIs is a potentially buggy heuristic process
> and should not be recommended here.

The Internationalization aspects have been discussed ad nausea in the WG.  Most of the i18n takes place in constructing the query (http://tools.ietf.org/html/draft-ietf-weirds-rdap-query) there the only elements that are subject to i18n are the DNS names used(in the queries) and their translation is well defined.

So what is left for transforming the URIs is the mapping between A- and U- Labels for the domain part of the URI itself. 

(Would sort of clarification help in the document?)

> 
> 9.2 
> "Under most scenarios" -- a few scenarios would be helpful.
> 

Action for editors?

Thanks for the Review.

--Olaf

---

From: Barry Leiba <[email-masked]>
Date: Mon, 12 Aug 2013 21:56:30 +0200

> If you mean "No business asking" then that is addressed in the last paragraph of 5.3.

404 is meant to say that the URL you're asking for doesn't exist (or
the server isn't willing to disclose that it exists).

When you use HTTP to retrieve a web page, there doesn't need to be a
distinction between "the web page doesn't exist" and "the web page is
empty" (that is, there's no information for me to give you).  I'll
just give you no information.

When you use RDAP, presumably there *is* a useful distinction between
the two.  Larry's questioning whether it's wise to use 404 for the
latter -- what you're asking for exists, but there's nothing to say
about it.

And so the question is whether there's a useful distinction in RDAP
between "you're querying about something that doesn't exist" and
"you're querying about something that exists, but there's no
information available about it."  If not, then 404 might be OK.  If
so, though, there should be different status codes, and 404 belongs to
the former.

Barry

---

From: Barry Leiba <[email-masked]>
Date: Tue, 13 Aug 2013 14:46:17 +0200

> I can see 3 cases, which (I think) are all addressed:
>
> * Malformed query (I cannot answer this type of query) (5.4: 400)
> * I can parse the query but have no data (5.3 first paragraph: 404)
> * I can parse the query but don't want to hand you the data (5.3: 4XX range, with optional information in the body)
>
> The last option is really of the form "there's no information for me to give you"

Hm.

Specific example:

I make a query to you at this URL: http://rdap.example.com/ip/203.0.113.0/24

That is clearly a properly formed query, so 400 is not on the table.

Case 1: You are *not* the right place to ask about 203.0.113.0/24.
This is what the HTTP 404 code is meant for, and I would think you'd
respond with a 404.

Case 2: You *are* the right place to ask about 203.0.113.0/24, but
your policies do not allow you to give me the data.
This is your third case above, and you will respond with some 4XX code.

Case 3: You *are* the right place to ask about 203.0.113.0/24, and
your policies allow you to give me the data... but there's just no
data to give me.
Is this a real case?  Can it happen?  If it happens, what status code
will you send back?

If case 3 can't happen, and it really is only cases 1 and 2 (and
malformed), then we're done, and the stuff about 404 is fine.  If case
3 can happen, we need to talk about it.

Barry

---

From: Barry Leiba <[email-masked]>
Date: Tue, 13 Aug 2013 15:56:15 +0200

> In case 3, if 203.0.113.0/24 is not an exact boundary for a network
> registration, the proper thing to do according to the query draft is to
> return the network registration that encompasses 203.0.113.0/24. Therefore
> I think case 3 cannot happen. There are similar semantics for autnum
> ranges. For domains, name servers, and entities, either they exist or they
> don't.
>
> Does the help?

It does.  If it's not possible to have a valid query that's been sent
to the right place, but to have no data to return... then we're OK.

Perhaps part of the problem here is that using-http seems to depend on
rdap-query, but there's no normative reference to rdap-query here
(only from rdap-query to using-http).  Does using-http really make
*any* sense at all without rdap-query?

Barry

---

From: Olaf Kolkman <[email-masked]>
Date: Tue, 13 Aug 2013 09:41:30 +0200

<Hats off, and possibly showing my RESTfull/HTTP ignorance>

Am I misreading? Do not hesitate to use the clue-bat, if I am.

--Olaf

---

From: Andy Newton <[email-masked]>
Date: Tue, 13 Aug 2013 13:32:02 +0000

On 8/13/13 8:46 AM, "Barry Leiba" <[email-masked]> wrote:

>
>Specific example:
>
>I make a query to you at this URL:
>http://rdap.example.com/ip/203.0.113.0/24
>

Barry,

Does the help?

-andy

---

From: "Martin J. Dürst" <[email-masked]>
Date: Wed, 14 Aug 2013 21:58:17 +0900

> 3 can happen, we need to talk about it.

There is no need for a special status code for empty documents, they can 
be expressed in HTTP.

Just in case case 3 could happen, what about something like
Content-Length: 0

Or an 'empty' XML or JSON document or whatever the payload is?

Regards,   Martin.

---

From: Mark Baker <[email-masked]>
Date: Wed, 14 Aug 2013 14:12:22 -0400

Greetings,

I'd like to step back a moment from the minutiae of the specification
to ask the meta question, "Why is this needed"? What's so special
about registration data that it needs a separate specification about
how HTTP should be used with it? HTML doesn't have one of those, nor
does any other data format on the Web that I'm familiar with.

The introduction states "The purpose of this document is to clarify
the use of standard HTTP mechanisms for this application", but I don't
understand what needs clarification. Indeed, many of the requirements
of this "protocol" imply a profile of HTTP which is quite non-RESTful
(where REST was apparently the motivational style for this work, kudos
for that). Consider;

sec 4.1 "Accept header". There's no normative requirements in this
section, and it appears to just summarize the meaning of Accept.
What's the value?
sec 4.2 "Query Parameters". If this were RESTful, then that wouldn't
be required because RESTful clients only construct URI based on the
explicit direction of a server. This MUST could also be interpreted as
defining the equivalence of URIs, for example
http://example.org/ip/192.168.1.1 and
http://example.org/ip/192.168.1.1?someparam=somevalue, but in a
non-RESTful way as the equivalence isn't made visible to non-RDAP
aware applications.
sec 5.1 "Positive Answers" seems as unnecessary as 4.1 as it simply
rehashes what HTTP already does. Ditto for 5.2, 5.3, and 5.4. I fear
that these sections could be interpreted by implementors as
restricting/subsetting the types of possible HTTP interactions; though
I applaud the final paragraph of section 3 which expresses a desire
for this not to be the case, this specification could easily be
interpreted as a profile, making reuse of existing HTTP software more
difficult.

5.5 is also not strictly necessary for the same reasons above, but
since 429 is a relatively new but valuable status code, calling out
its value for this application shouldn't be a problem. It just seems
more like a community best-practice that should be in wiki somewhere
rather than in specification prose.

I haven't studied the breadth of the WEIRDS work product, but it seems
to me that it's making a mountain out of a molehill in trying to solve
what appears to be a simple problem. To use the Web correctly, IMO,
all that should be required is a hypermedia data format and perhaps
some additional link types. Or perhaps just the latter, if HTML were
used with rich markup such as Schema.org or RDFa (probably a fairly
radical idea at this stage, but it's a good option IMO).

Mark.

---

From: Spencer Dawkins <[email-masked]>
Date: Wed, 14 Aug 2013 08:32:50 -0500

On 8/14/2013 7:58 AM, "Martin J. Dürst" wrote:
> There is no need for a special status code for empty documents, they 
> can be expressed in HTTP.
>

FWIW, I was sympathetic to Larry's concern about 404 overload expressed 
during IESG evaluation, at the Comment level. Of course, I'm not the 
right guy to say whether a new status code is required.

If you tell people how to distinguish between "I can't tell you what I 
know" and "I can't tell you because I don't know anything" using a 
zero-length document in the response, that would address my comment 
without introducing a new status code.

Thanks,

Spencer