Subject: [weirds] Edits/Comments on draft-sheng-weirds-icann-rws-dnrd-01

From: Wil Tan <[email-masked]>
Date: Wed, 14 Mar 2012 11:32:43 +1100

Hi Steve, Francisco's and Ning,

On Wed, Mar 14, 2012 at 10:52 AM, Wil Tan <[email-masked]> wrote:

> On Tue, Mar 13, 2012 at 3:02 PM, Steve Sheng <[email-masked]>
>  wrote:
>
>>
>>  We welcome feedback on this draft. The draft also identifies serveral
>> outstanding issues that need further work. Our question is are there more
>> domain registries willing to build on this and work together on this?
>>
>>
> I'm employed by Cloud Registry. We support the efforts and are willing to
> contribute towards the cause, be it document drafting, review or
> prototyping and interoperability tests.
>
>
Thank you for your great efforts.

I have gone through the draft and made some edits, and left some comments,
included here in a diff-like format (for my convenience, apologies if it's
a little hard to read):

@@ -124,9 +124,9 @@
 1.1.  Domain Name Registration Data

    Domain Name Registration Data is the information that a registrant
-   provides when s/he acquires or is assigned a domain name.  Many
+   provides when applying for or registering a domain name.  Many
    domain registries and registrars ([RFC3707]) provide public access to
-   some of these data via the WHOIS protocol ([RFC3912]) or a web
+   a subset of the data via the WHOIS protocol ([RFC3912]) or a web
    interface.  For example, for interactions between ICANN Accredited
    Generic Top Level Domain (gTLD) registrars and registrants, the data
    elements are specified in the current Registrar Accreditation

@@ -153,9 +153,9 @@
    defined aspects: 1) The "verbs" of the service are strictly those
    defined by the HTTP methods HEAD, GET, PUT, POST, and DELETE, 2) The
    "verbs" are used to act upon resources, and 3) resources are
-   addressable using URLs
+   addressable using URIs.

-   Whois services, in general, are read-only services.  Therefore URL
+   Whois services, in general, are read-only services.  Therefore URI
    patterns [RFC3986] presented here are only applicable to the HTTP
    [RFC2616] GET and HEAD methods.

@@ -206,7 +206,7 @@

    The server accepts standard HTTP "GET" requests for the resources it
    serves.  The client sends its request with the following URI
-   structure.  The URI structure start with a base URL specified by each
+   structure.  The URI structure starts with a base URL specified by each
    domain registry or any other service provider offering this service.
    The base URL will be appended with resource type specific path
    segments.  The base URL may contain its own path segments (e.g.

@@ -238,7 +238,7 @@
 3.1.  Domain

    Queries for information about domain names are of the form /domain/
-   example.tld/... where the path segment following 'domain' is an
+   example.tld/... where the path segment following 'domain' is a
    domain name, in this case example.tld.  Path segments following the
    domain name can target specific information associated with the
    domain name in the following way:

@@ -325,6 +325,9 @@
    hostname [RFC1123], IPv4 [RFC0791] or IPv6 [RFC5952] address of the
    hostname.

+>>> This is overloading the "XXX" slot with different semantics. It'd be
+>>> good to use it just as a hostname, leaving IPv4/6 addresses as queries.
+
    Here are some example queries:

    base URL: http://whois.tld/somepath

@@ -355,27 +358,43 @@
       /registrar/"Network Solutions, LLC"/ - query the registrar names
       "Network Solutions.  LLC"

+>>> As with my comments in 3.3 above, this should be:
+>>>   /registrar/?name=Network%20Solutions,%20LLC
+
       /registrar/123/ - queries the registrar whose ID is 123.

 3.5.  Signaling Response Formats

    The default response format for the RWS-RDNRD server is XML.
    However, additional formats such as JSON, HTML or plain text can be
-   provided.  The client signals the preferred format using the standard
-   HTTP "Accept:" header.  For example, if the client wishes to receive
-   JSON [RFC4627] response, it SHOULD put the "application/json" MIME
+   provided.  The client signals the preferred format using standard
+   HTTP Content Negotiation [RFC2616] mechanisms. In particular, the
+   HTTP "Accept:" header MAY be to indicate content type (format)
preferences.
+   For example, if the client wishes to receive
+   JSON [RFC4627] response, it SHOULD specify the "application/json" MIME
    type in the Accept header.  Servers SHOULD respond with JSON
    responses when this MIME type is present in the Accept header in
    accordance with the preference rules for the Accept header in HTTP
    [RFC2616].  However the use of multiple MIME types in the Accept
    header is not supported.

+>>> Why is it not supported? The server should be able to process
+>>> multiple MIME types in the Accept header by following standard
+>>> HTTP "q" (quality) parameter behaviour.
+
    Possible response formats and their signaling methods include:

       XML (default) - application/xml

       JSON - application/json

+      YAML - text/x-yaml or text/yaml
+
+>>> I can't seem to find an officially assigned media type for YAML
+>>> but would contend that it is highly useful to have this as a
+>>> very very human-readable yet machine parsable format.
+>>> Try "whois -h whois.gandi.net gandi.net" to see what I mean.
+
       HTML - text/html

       plain text - text/plain

-- 
Wil Tan
CTO
Cloud Registry <http://www.cloudregistry.net>

---

From: Steve Sheng <[email-masked]>
Date: Tue, 13 Mar 2012 22:29:11 -0700

Hi Wil, thanks very much for the input, see inlined responses, basically I agree with the vast majority of your edits, I have a few questions, and  clarification from you would be very helpful. :

From: Wil Tan <[email-masked]<mailto:[email-masked]>>
Date: Tue, 13 Mar 2012 17:32:43 -0700
To: "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: [weirds] Edits/Comments on draft-sheng-weirds-icann-rws-dnrd-01

On Wed, Mar 14, 2012 at 10:52 AM, Wil Tan <[email-masked]<mailto:[email-masked]>> wrote:
On Tue, Mar 13, 2012 at 3:02 PM, Steve Sheng <[email-masked]<mailto:[email-masked]>> wrote:

I'm employed by Cloud Registry. We support the efforts and are willing to contribute towards the cause, be it document drafting, review or prototyping and interoperability tests.

I have gone through the draft and made some edits, and left some comments, included here in a diff-like format (for my convenience, apologies if it's a little hard to read):

@@ -124,9 +124,9 @@

>> k, updated the draft.

@@ -153,9 +153,9 @@

>> k, updated the draft.

>> k, updated the draft.

@@ -206,7 +206,7 @@

>> , updated the draft.

@@ -238,7 +238,7 @@
 3.1.  Domain

    domain name in the following way:

>>k, updated the draft.

@@ -325,6 +325,9 @@

@@ -355,27 +358,43 @@

>> not sure I understand, could you provide more examples?

+   HTTP "Accept:" header MAY be to indicate content type (format) preferences.

>> ok, updated the draft.

>> ok, I will look into this further.

       JSON - application/json

+>>> Try "whois -h whois.gandi.net<http://whois.gandi.net> gandi.net<http://gandi.net>" to see what I mean.
+

>> ok, I checked this WHOIS output, it does not seem very human readable to me. What do others think about adding YAML?

       HTML - text/html

       plain text - text/plain

---

From: Wil Tan <[email-masked]>
Date: Wed, 14 Mar 2012 22:31:58 +1100

> >> not sure I understand, could you provide more examples?
I see /registrar/123/ as the URI to the resource identified by the
registrar ID "123", akin to a database lookup.

The other form /registrar/"Networks Solutions, LLC"/ seems to carry more of
a search semantics to me. This draft is silent about searching or returning
multiple matches, but that's exactly what's needed if the lookup doesn't
produce an exact match.

Do you have any plans to work on specifying the behaviour when multiple
matches are found?

> >> ok, I checked this WHOIS output, it does not seem very human readable
> to me. What do others think about adding YAML?
>
>
I think this is probably tangential or at least a detail that we can work
out at a later iteration of the draft, or if the representation/format gets
split out into a different draft, as others have suggested.
The last thing I want to start is another long thread about formats, so I
will refrain from commenting.

.wil

---

From: Steve Sheng <[email-masked]>
Date: Wed, 14 Mar 2012 10:00:54 -0700

Excellent point, search is not addressed in the current draft. I will add this to the list of things to do.

Thanks,
Steve

From: Wil Tan <[email-masked]<mailto:[email-masked]>>
Date: Wed, 14 Mar 2012 04:31:58 -0700
To: Steve Sheng <[email-masked]<mailto:[email-masked]>>
Cc: "[email-masked]<mailto:[email-masked]>" <[email-masked]<mailto:[email-masked]>>
Subject: Re: [weirds] Edits/Comments on draft-sheng-weirds-icann-rws-dnrd-01

I see /registrar/123/ as the URI to the resource identified by the registrar ID "123", akin to a database lookup.

The other form /registrar/"Networks Solutions, LLC"/ seems to carry more of a search semantics to me. This draft is silent about searching or returning multiple matches, but that's exactly what's needed if the lookup doesn't produce an exact match.

Do you have any plans to work on specifying the behaviour when multiple matches are found?