Subject: [weirds] FW: I-D Action: draft-kong-dnrd-ap-response-json-00.txt

From: "Ning Kong" <[email-masked]>
Date: Sun, 3 Jun 2012 15:39:27 +0800

Hi all,

This is a 00 draft to describe a response format in JSON for name
registries. This document has been reviewed and improved by the design team.
The following issues are still needed to be further discussed.
	1) As for the naming of the terms, should we try to follow the EPP
specs or just use some more self-descriptive and unified terms? For example,
"roid" or "domainID" for naming the ID of domain object, which one is
better?
   2) Is the extension interface necessary or not?

Any comments are appreciated.

Cheers,
Ning

-----Original Message-----
From: [email-masked] [mailto:[email-masked]]
On Behalf Of [email-masked]
Sent: Sunday, June 03, 2012 3:12 PM
To: [email-masked]
Subject: I-D Action: draft-kong-dnrd-ap-response-json-00.txt

A New Internet-Draft is available from the on-line Internet-Drafts
directories.

	Title           : Domain Name Registration Data Access Protocol
Response Format defined in JSON
	Author(s)       : Ning Kong
                          Linlin Zhou
                          Jiagui Xie
                          Sean Shen
	Filename        : draft-kong-dnrd-ap-response-json-00.txt
	Pages           : 21
	Date            : 2012-06-03

   This document describes a response format for registration data
   (Whois data) through RESTful Web-based Service.  This response format
   is defined in JavaScript Object Notation (JSON).

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-kong-dnrd-ap-response-json-00.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

This Internet-Draft can be retrieved at:
ftp://ftp.ietf.org/internet-drafts/draft-kong-dnrd-ap-response-json-00.txt

The IETF datatracker page for this Internet-Draft is:
https://datatracker.ietf.org/doc/draft-kong-dnrd-ap-response-json/

_______________________________________________
I-D-Announce mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/i-d-announce
Internet-Draft directories: http://www.ietf.org/shadow.html or
ftp://ftp.ietf.org/ietf/1shadow-sites.txt

---

From: Alex Sergeyev <[email-masked]>
Date: Mon, 11 Jun 2012 16:51:49 -0400

Hi Ning and list members,

I hoped to participate in discussion about this proposal for few days
but I guess I should be one to say at
least something first  :)

>   "roid" or "domainID" for naming the ID of domain object, which one is

This is my very personal opinion, I don't see the "ROID" as
"domainID". There is just one domain-id
and it's "domain name". For the generalization of info that you can
get from WEIRDS, it could be called
"local-id" some other way. I'm not a big fan of "roid" as a key (and I
like local because it's applicable for
my other info services that I'm putting together as an  experiment,
some of them clearly have some sort
of "local-id" and others don't)

In terms of general "camelCaseKey" or "dash-separated-key" I have no
preference, I think working group should
just agree on one or another.

>   2) Is the extension interface necessary or not?

It sounds too restrictive for a task of "information providing
service" to have such "extension" section. I think
that there should be some common sense concept:
* you must provide certain fields
* you can provide more
* you should not provide information not directly related to object
that you're querying that could be provided
  separately

E.g it's clear for me that if I'd want to provide some info-service
about previous ownership of the object, I would
not stuff that history to an object itself. I'd make
"history-of-xxxxx" and refer to it from object itself. Again, note
that I'm trying to stay above "domain whois replacement"  here.

Same time you don't want to invent "timestamp" object and refer to it
from all fields because it's just plain abuse.

> Any comments are appreciated.
Few more questions/comments then :)

1. You use keys "nameserver" and "contact"  for lists of things...

Could you comment on reasons for not using plurals?

I also wonder what others think on using plain array for contacts
rather than associative array with "tech/admin/billing"
keys (and plain arrays of contact IDs inside of it).

I also wondering why you put it this way
{
    domain:{domainName:.... (and other fields here)},
    nameserver:[],
    contact:[],
    registrar:{},
    extension:{}
}

and not this way:
{
    domainName:...
    (and other fields here)
    nameserver:[],
    contact:[],
    registrar:{},
    extension:{}
}

It just makes more sense for me to have some identifying fields at the
top level of json, not iside of "domain" sub-structure.

2. Way of referencing related objects

Your proposal is different from
http://tools.ietf.org/html/draft-newton-et-al-weirds-rir-json-response-01
in order
to make links to something related.

I don't have clear preference but I like having "uris" section in the
end with list of references (as in Newton's proposal) because
it gives flexibility of adding links where more info needed later
without restructuring the data.

3. I'm not sure about mix of hosts and nameservers in one structure.

4. Anybody else thinks that "clientID" and "createID" (and "updateID"
in some cases) should have better names and be
    linked to parent WEIRDS service to find out about those registrars?

--
Alex Sergeyev
Sr. Engineer of Dyn Labs

---

From: Andy Newton <[email-masked]>
Date: Mon, 11 Jun 2012 21:46:57 +0000

> of "local-id" and others don't)

I don't really understand "local-id". 

But an identifier for a domain registration is not necessarily the same thing as the domain name. Let's say example.com has been registered four separate times, the domain id might change for each registration whereas the domain name would be the same for each registration.

-andy

---

From: Alex Sergeyev <[email-masked]>
Date: Mon, 11 Jun 2012 17:59:41 -0400

Andy, others,

> But an identifier for a domain registration is not necessarily the same thing as the
> domain name. Let's say example.com has been registered four separate times,
> the domain id might change for each registration whereas the domain name would
> be the same for each registration.

I agree and understand this, I just think that it's not some sort of
universal id out there,
ROIDs from different registries could be same and essentially it's
some sort of "localized
identifier" for the object inside of the queried WEIRDS service.

I don't really care about name, I'm just saying that "roid" is
specific to domain names
and folks like more generic term that they can use for other objects
(say in ip network
registration records for same purpose of tracking same network re-registered to
another client, they might choose some sort of generic name)

--
Alex.

---

From: Patrick Vande Walle <[email-masked]>
Date: Tue, 12 Jun 2012 07:30:10 +0200

Thanks for this, Ning.

I have some comments regarding  3.3.1. Objects in the Contact Response

Say  the registry  has a policy that does not allow the display of all
or part of the contact info to the querying party
We could either

- not return the corresponding field
- return the field name, but with an empty value
- return the field name, and a field value that could be either
         - a text string saying the value cannot be displayed by policy,
whose content is up to the registry operator
         - a return code, sort of like HTTP 401  that would indicate the
querying party  is not authorized to view that information. 

As for the fields themselves, it has been pointed out that telefax
numbers are of little use these days, and that other channels of
communications may be more responsive.  Facebook and Twitter come to
mind.  However, these type of services come and go,. They might be out
of fashion by the time the work of this WG gets actually deployed. 
There should be a mechanism that allows for the extension of the contact
information, without requiring an update the corresponding RFCs. 

Cheers,

Patrick Vande Walle

On 03/06/12 09:39, Ning Kong wrote:
> weirds mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/weirds
>

---

From: "Ning Kong" <[email-masked]>
Date: Tue, 12 Jun 2012 17:25:09 +0800

Hi Alex,

Thanks for your comments. Please see my feedback inline.

> This is my very personal opinion, I don't see the "ROID" as "domainID". There
> is just one domain-id and it's "domain name". For the generalization of info
> that you can get from WEIRDS, it could be called "local-id" some other way.
> I'm not a big fan of "roid" as a key (and I like local because it's applicable for
> my other info services that I'm putting together as an  experiment, some of
> them clearly have some sort of "local-id" and others don't)
I think there is something opaque in our definition of ROID. The definition might be modified as the following.
	roid -- the identifier assigned to the domain name when the object was created in the repository by a registry.
So I agree with you that this ID (roid or domainID or other better name) should be local.

> It sounds too restrictive for a task of "information providing service" to have
> such "extension" section. I think that there should be some common sense
> concept:
In this version, we don't point out which fields are mandatory. I think it will take some time and energy for us to make sure the certain fields. If possible, I'd like to contribute on this work and correspondingly update the following version.

> * you can provide more
Agree. So we propose the extension interface in this document. I'd like to know whether you don't like to provide more info in the special extension section.

> * you should not provide information not directly related to object that
> you're querying that could be provided separately
We try to follow this rule. See the contact objects in the domain name response.

> Could you comment on reasons for not using plurals?
I think using plurals is better.

> I also wonder what others think on using plain array for contacts rather than
> associative array with "tech/admin/billing"
So you prefer the following design?
  "contact": {
    “tech”: {
      "contactID": "xyz",
      "contactUri": "http://example.com/dnrd-ap/contact/xyz/"
   },
    “admin”: {
      "contactID": "xyz",
      "contactUri": "http://example.com/dnrd-ap/contact/xyz/"
   },
    “billing”: {
      "contactID": "xyz",
      "contactUri": "http://example.com/dnrd-ap/contact/xyz/"
   }
 }
I can't tell which design is better. I think both of them are acceptable, whether from development aspect or drafting aspect. More comments are appreciated.

> I also wondering why you put it this way {
> It just makes more sense for me to have some identifying fields at the top
> level of json, not iside of "domain" sub-structure.
Your suggestion seems more reasonable. The intent of our design is we'd like to separate the basic info of a domain from its other related sections, especially the extension section. By this design, it's easy to let the user only acquire the basic info of a domain. E.g. http://example.com/dnrd-ap/example.com/domain
I'd like to get more comments on this point.

> I don't have clear preference but I like having "uris" section in the end with
> list of references (as in Newton's proposal) because it gives flexibility of
> adding links where more info needed later without restructuring the data.
I don't think our design is less flexible than the one you mentioned above.

> 3. I'm not sure about mix of hosts and nameservers in one structure.
Me either. I think separating them into two objects may be better. Any more comments?

>     linked to parent WEIRDS service to find out about those registrars?
We use these names according to the EPP specs. We'd like to accept better names in future if we can get consensus.

Cheers,
Ning

---

From: Patrick Vande Walle <[email-masked]>
Date: Tue, 12 Jun 2012 14:46:13 +0200

On 12/06/12 13:31, Bob Bruen wrote:
> While this does not detract from your point, and this is not a
> technical issue, the example of a registry/registrar having a policy
> of not displaying all or part of a whois record is not acceptable. The
> complete record should always be available.

Hi Bob,

My point is that we design a system that needs to be used by more than
just the registries/registrars  that are under contract with ICANN,
under their current contractual obligations.   If this is acceptable or
not is a matter of policy, which is not the goal of this WG. 

Hence, the end product needs to be flexible enough to address all
possible uses,  including the legal requirements that can be put on
registries and registrars.  What this WG produces should not have a bias
towards one policy or another.  BTW, this is also reflected in ICANN's
RFP for an open source implementation : 
http://www.icann.org/en/news/rfps/restful-whois-16may12-en.pdf  (#2.5)

Patrick

---

From: "Ning Kong" <[email-masked]>
Date: Tue, 12 Jun 2012 22:04:55 +0800

Hi Patrick,

> Thanks for this, Ning.
My pleasure.

> Say  the registry  has a policy that does not allow the display of all or
part of
> the contact info to the querying party We could either
> 
I think you put forward a general issue. IMO, the HTTP draft
(draft-designteam-weirds-using-http-00) as the common infrastructure
document is suitable to cover this point. For example, a new section (e.g.
5.5 Unauthorized Answers) may be added to propose the corresponding response
mechanisms.
BTW, I think another optional response which might also be considered for
this scenario is that returning not only the field name and a text saying
the querying party is not authorized, but also a reference to tell the
requester how to acquire the authorized answers. Through this reference, if
the requester can meet the corresponding requirements (e.g. providing
correct authentication info or a token authorized by the owner), he/she can
further acquire the authorized answers. To consider this kind of response,
the authentication mechanism of RESTful WHOIS services needs to be
correspondingly designed.

> As for the fields themselves, it has been pointed out that telefax numbers
are
> of little use these days, and that other channels of communications may be
> more responsive.  Facebook and Twitter come to mind.  However, these
> type of services come and go,. They might be out of fashion by the time
the
> work of this WG gets actually deployed.
So, I wonder whether we should consider discarding some traditional WHOIS
data elements or adopting some new fashionable ones (e.g. IM, SNS) as basic
fields.

> information, without requiring an update the corresponding RFCs.
We have the extension interface in the draft. Do you think this can meet the
above requirement?

Cheers,
Ning

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 10:29:31 -0400

> whose content is up to the registry operator

Please, not this.

The whole point of WEIRDS is that it's supposed to be _machine
parsable_.  Putting magic strings in the answer doesn't qualify.  If
we're going to do that, we might as well just do whois-bis, put it on
port 48043, explicitly state that everything UTF-8, and stop work.  

> communications may be more responsive. 

Maybe contact information should follow vCard?  (*ducks*)

A

-- 
Andrew Sullivan
[email-masked]

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 10:42:23 -0400

> 5.5 Unauthorized Answers) may be added to propose the corresponding response

This raises an interesting and vexing issue, I think.

As we're working now, we are talking about responses and requests.
But in a REST context, it seems to me, you either get the resource or
you don't.  

One of the goals so far has been to permit differential levels of
service depending on credentials.  (I believe quite strongly that if
we do not provide that functionality, we will have completely botched
this work.)

It seems to me therefore that data we return must be much more linked
and much less cohesive.  For instance, in the present draft, the
response for domains includes contact data, nameserver data, and so
on.  But instead, that all ought to be linked data, so that it is
possible to return the appropriate response (e.g. the data vs. http
401 or 403 errors) depending on who asks for it.  It seems also that
it might be possible to create a roll-up type resource that provides
all the answers in one go, at the cost of authorization being the
denied if any of the underlying resource permissions aren't available.

Thoughts?

Best,

A 

-- 
Andrew Sullivan
[email-masked]

---

From: Andy Newton <[email-masked]>
Date: Tue, 12 Jun 2012 11:02:45 -0400

> denied if any of the underlying resource permissions aren't available.

How did you make that logic jump? Redacting information isn't rocket 
science.

Our experience is that people want all the information in one go. We 
initially rolled out the service with the data objects separated out, 
and most people did not like that. The other downside is that a client 
is gonna send multiple queries regardless.

Finally, this seems like a corner case. There has yet to be a single 
example given on this list of any authorization scheme or needed 
authentication mechanism.

-andy

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 11:56:43 -0400

> How did you make that logic jump? Redacting information isn't rocket

I suppose the alternative is to redact information in responses
according to the credentials presented.  We could use some sort of
http header to warn that some data has been redacted because of lack
of authentication?

> Our experience is that people want all the information in one go.

I'm sure this is true.  Of course, this is partly because everyone has
a large number of tools built around the assumptions of WHOIS.  I
think our hope is to offer something better, right?

> authentication mechanism.

That's not true.  First, Murray and John have both said that they'd be
entirely willing to trade away the accessibility of contact
information for authenticated confirmation that two resources
(e.g. two names or two netblocks) are related according to some
criteria.  I've heard law enforcement people say the same thing, so
I'm sure it's valuable.  Second, we know that name registrants
frequently futz with their contact data in a bid to protect their
personally identifying information from being completely and trivially
public.  Addressing any of these cases is going to require rules about
authentication and authorization.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: Andy Newton <[email-masked]>
Date: Tue, 12 Jun 2012 13:16:29 -0400

> http header to warn that some data has been redacted because of lack

That works for me. Suggestions?

> authentication and authorization.

I would like to see a concrete example of the first use case as 
"related" is a fairly subjective term.

The second use case I understand and is easy to do with simple redaction.

-andy

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 15:22:35 -0400

> That works for me. Suggestions?

Well, that's the problem.  The natural place to put this, AFAICT, is
in the Warning: header field in an http response.  I suspect the
right thing to to would be to specify that a client MAY use
such-and-thus Warning: header as an indication that it could get more
information if it had the right credentials.

Unfortunately, I can see nothing in RFC 2616 that is a natual
candidate.  The httpbis WG is working on a replacement, however, and
in part 7 (!) of that replacement there is a Warn Code Registry
defined.  Maybe that's what we ought to do.  It will have no effect on
simple web-browser type clients, but a more sophisticated client could
use the warn code.  I can ask about this on httpbis@ if it seems worth
chasing.

> >I'm sure it's valuable.

> "related" is a fairly subjective term.

"Please tell me if $object1 and $object2 are registered by the same
registrant," for instance.  (Unpacking "same registrant" is going to
be local policy-dependent.  Maybe it will mean "same street address"
or "same email domain" or merely "same registrant id".)  The argument
that anti-abuse and law enforcement people make about needing
"complete and accurate" WHOIS information in very many cases boils
down to, "I need to know whether these networks|netnames are under the
control of the same person."  Anti-abuse people don't really _care_
who it is exactly, and LE people could get a warrant if they needed to
know who it was exactly.

> The second use case I understand and is easy to do with simple redaction.

Yes, but if I'm the client I want to know that the data is there, but
that I can't have it.  Security people would call that an information
leak, but in this case it's a feature, because we want a signal to
this effect.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: "John Levine" <[email-masked]>
Date: 12 Jun 2012 20:24:23 -0000

>think our hope is to offer something better, right?

Yes, but I think that people building servers would be unhappy to find
that what they had thought was one query is now six queries, since
that turns a query rate of N into a rate of 6N.

I can think of a variety of straightforward ways to indicate partial
redaction, other than a non-standard HTTP header, from a reserved
field value that means redacted (a single space, perhaps) to adding
IS-REDACTED flags to the components that might be affected.

R's,
John

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 16:34:25 -0400

> IS-REDACTED flags to the components that might be affected.

I thought we were doing REST, not
REST-except-where-everything-is-inlined-then-work-hard?  We can't
possibly be the only people on earth who want to offer different views
of the same data depending on the credentials of the query source.
The natural way to do that is surely not "bodge up the data so you
have to parse it to know what it means".

One of the things that hosed IRIS, I think, was the difficulty on the
client side.  If the plan here is that we need to make the clients
smart enough to tell the metadata from the data by parsing it, I would
like to suggest that we'll fail again.  DNS has now a 25 year hangover
from the fact that the control plane and the data plane are not
clearly delineated, and I really don't see a reason to repeat that
mistake.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: Andy Newton <[email-masked]>
Date: Tue, 12 Jun 2012 16:41:08 -0400

> clearly delineated, and I really don't see a reason to repeat that

How is forcing a client to requery 3 or 4 times less cumbersome?

I use to believe as you do, but experience has taught me differently.

-andy

---

From: Andrew Sullivan <[email-masked]>
Date: Tue, 12 Jun 2012 16:58:13 -0400

> How is forcing a client to requery 3 or 4 times less cumbersome?

I am not trying to make a client requery 3 or 4 times.  I'm trying to
ensure that we have the basic elements in place so that we can
actually offer the things we said we would.  This might mean
additional URIs so that it is easy to combine results.  But as I read
REST, you should start with the atoms and work out.  Even if nobody
ever uses the atomic bits.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: Andy Newton <[email-masked]>
Date: Tue, 12 Jun 2012 17:04:57 -0400

> ever uses the atomic bits.

We may have reached a point where we are talking past each other here.

In the context of the RIR-JSON draft, can you provide a concrete example 
for the need for additional URIs in a manner that is already not 
provided? And where redaction and a redaction-happened-flag are not 
adequate?

-andy

---

From: "Linlin Zhou" <[email-masked]>
Date: Wed, 13 Jun 2012 11:29:15 +0800

Hi,
Thanks for comments.
This draft intends to specify the common response format. So we put more
focus on the technical part. In this version, just a brief paragraph before
section 3.1 is provided related to policy.
Having read the policy & tech thread, IMHO, both the authentication
mechanism and policy making will affect the query and response drafts. The
authentication mechanism supplies the technical solution, and policy
decisions raise the specific requirements. Until now ,at least I am not
quite clear about the authentication mechanism that will be adopted and the
specific requirements for differential classes of service. 
So, I think the above work should be done in parallel, in which way, the
protocol could be improved better.
We have done some research wok on authentication, but need more help and
contribution from experts on web authentication and security. We also
welcome more comments from policy experts, providing some specific
requirements for the draft.

Thanks & regards,
Linlin Zhou
CNNIC

> From: [email-masked] [mailto:[email-masked]] On Behalf
Of
> Andrew Sullivan
> Sent: Tuesday, June 12, 2012 10:42 PM
> To: [email-masked]
> Subject: Re: [weirds] FW: I-D Action:
draft-kong-dnrd-ap-response-json-00.txt
> > 5.5 Unauthorized Answers) may be added to propose the corresponding
> > response mechanisms.
> 
> But in a REST context, it seems to me, you either get the resource or you
don't.
> 
> One of the goals so far has been to permit differential levels of service
> depending on credentials.  (I believe quite strongly that if we do not
provide
> that functionality, we will have completely botched this work.)
> 
> It seems to me therefore that data we return must be much more linked and
> much less cohesive.  For instance, in the present draft, the response for
> domains includes contact data, nameserver data, and so on.  But instead,
> that all ought to be linked data, so that it is possible to return the
appropriate
> response (e.g. the data vs. http
> 401 or 403 errors) depending on who asks for it.  It seems also that it
might
> be possible to create a roll-up type resource that provides all the
answers in
> one go, at the cost of authorization being the denied if any of the
underlying
> resource permissions aren't available.
> 
> Thoughts?
> 
> Best,
> 
> A
> 
> --
> Andrew Sullivan
> [email-masked]

---

From: Alex Sergeyev <[email-masked]>
Date: Wed, 13 Jun 2012 23:46:01 -0400

On Tue, Jun 12, 2012 at 4:41 PM, Andy Newton <[email-masked]> wrote:
>> REST-except-where-everything-is-inlined-then-work-hard?
>>...

I know it looks bad but doing 3-4 requests should not be a concern. Browsers
do that all the time, weirds clients may handle it too. HTTP has
keep-alive and all
(name your programming language) libs can do that.

-- 
Alex.