[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

Network Working Group                                           S. Sheng
Internet-Draft                                                  F. Arias
Intended status: Informational                                     ICANN
Expires: September 13, 2012                                    F. Obispo
                                                                     ISC
                                                                 N. Kong
                                                                   CNNIC
                                                          March 12, 2012


   A RESTful Web Service for Domain Name Registration Data (RWS-DNRD)
                  draft-sheng-weirds-icann-rws-dnrd-01

Abstract

   This document specifies a RESTful Web Service for querying Domain
   Name Registration Data (WHOIS data).

   The purpose of this document is to facilitate discussion and serve as
   input into a standards process in this area, currently being
   discussed on the Worthwhile Extensible Internet Registry Data Service
   (WEIRDS) mailing list (https://www.ietf.org/mailman/listinfo/weirds).

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 13, 2012.

Copyright Notice

   Copyright (c) 2012 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of



Sheng, et al.          Expires September 13, 2012               [Page 1]


Internet-Draft                  RWS-DNRD                      March 2012


   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Domain Name Registration Data  . . . . . . . . . . . . . .  3
     1.2.  REST and RESTful Web Service . . . . . . . . . . . . . . .  3
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  The Request  . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.1.  Domain . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     3.2.  Contacts . . . . . . . . . . . . . . . . . . . . . . . . .  6
     3.3.  Hosts  . . . . . . . . . . . . . . . . . . . . . . . . . .  6
     3.4.  Registrars . . . . . . . . . . . . . . . . . . . . . . . .  7
     3.5.  Signaling Response Formats . . . . . . . . . . . . . . . .  7
   4.  The Response . . . . . . . . . . . . . . . . . . . . . . . . .  7
     4.1.  Domain Names . . . . . . . . . . . . . . . . . . . . . . .  8
     4.2.  Contacts . . . . . . . . . . . . . . . . . . . . . . . . . 12
     4.3.  Host Names . . . . . . . . . . . . . . . . . . . . . . . . 14
     4.4.  Registrars . . . . . . . . . . . . . . . . . . . . . . . . 16
   5.  Error Codes  . . . . . . . . . . . . . . . . . . . . . . . . . 16
   6.  Formal XML Syntax  . . . . . . . . . . . . . . . . . . . . . . 16
     6.1.  Contact XML Schema . . . . . . . . . . . . . . . . . . . . 17
     6.2.  Domain Name XML Schema . . . . . . . . . . . . . . . . . . 17
     6.3.  Host XML Schema  . . . . . . . . . . . . . . . . . . . . . 17
     6.4.  Registrar XML Schema . . . . . . . . . . . . . . . . . . . 17
     6.5.  RWS XML Schema . . . . . . . . . . . . . . . . . . . . . . 17
   7.  Internationalization Considerations  . . . . . . . . . . . . . 17
     7.1.  Considerations for Querying IDNs . . . . . . . . . . . . . 17
     7.2.  Considerations for Display of Internationalized
           Registration Data  . . . . . . . . . . . . . . . . . . . . 18
     7.3.  Considerations for Indicating Language/scripts in
           Responses  . . . . . . . . . . . . . . . . . . . . . . . . 18
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 19
   9.  Security Considerations  . . . . . . . . . . . . . . . . . . . 19
     9.1.  URIs and IRIs  . . . . . . . . . . . . . . . . . . . . . . 19
   10. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 19
   11. Change History . . . . . . . . . . . . . . . . . . . . . . . . 19
     11.1. Changes from version 00 to 01  . . . . . . . . . . . . . . 19
   12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
     12.1. Normative References . . . . . . . . . . . . . . . . . . . 20
     12.2. Informative References . . . . . . . . . . . . . . . . . . 20
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21



Sheng, et al.          Expires September 13, 2012               [Page 2]


Internet-Draft                  RWS-DNRD                      March 2012


1.  Introduction

   This document describes a way for querying domain name registration
   data through a RESTful Web-based Interface.  This draft closely
   follows the query patterns set by the Internet Draft on RESTful WHOIS
   proposed by some Regional Internet Registries
   ([I-D.newton-et-al-weirds-rir-query]).

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
   domain registries and registrars ([RFC3707]) provide public access to
   some of these 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
   Agreement (RAA).  For country code Top Level Domains (ccTLDs), the
   operators of these TLDs set their own or follow their government's
   policy regarding the request and display of these data.  The Domain
   Name Registration Data defined here is intended to satisfy such
   public access services.

1.2.  REST and RESTful Web Service

   REST stands for Representational State Transfer.  It is a set of
   architectural constraints that is developed as an abstract model of
   the Web architecture.  These constraints include: client-server
   model, stateless, cacheable, layered system, code on demand
   (optional), and uniform interface.  REST was used to guide the
   redesign of the Hypertext Transfer Protocol (HTTP) and Uniform
   Resource Identifiers (URI).  It is widely regarded as the
   architecture of the Web today.  Principles of REST have been used to
   design other protocols such as the ATOM publishing protocol.

   A RESTful web service is a web service implemented using HTTP and the
   principles of REST.  It is a collection of resources, with three
   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

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






Sheng, et al.          Expires September 13, 2012               [Page 3]


Internet-Draft                  RWS-DNRD                      March 2012


2.  Terminology

   For convenience, this implementation can be referred to as the
   "RESTful Web Service for Domain Name Registration Data" or "RWS -
   DNRD".  The following terminology is used by this specification:

      Domain Name Registration Data (DNRD) - the information that
      registrants provide when registering a domain name and that
      registrars or registries supplement with registry or registrar
      specific information.

      URI - A Uniform Resource Identifier as defined in [RFC3986].

      IRI - An internationalized Resource Identifier as defined in
      [RFC3987].

      Resource - A network-accessible data object or service identified
      by an URI, as defined in [RFC2616].  In this context, resources
      refers to the registration data objects.

      Representation - An entity included with a request or response as
      defined in [RFC2616].

   Additionally, we use ".tld" as a convention in this document to
   represent, generically, any top level domain (TLD) in the Domain Name
   System (DNS).


3.  The Request

   As its name implies RWS-DNRD is Web-based, i.e., uses HTTP [RFC2616]
   as its transport.  Given its RESTful nature it only uses the standard
   HTTP methods.  And given it is read-only, it only uses the GET and
   HEAD methods.

   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
   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.
   http://whois.tld/... or http://whois.tld/restful-whois/...).

   The resource type path segments are:

      'domain' - information about the domain including registration
      information, contact information, host information and possible
      other details specified by registries' Whois policy.



Sheng, et al.          Expires September 13, 2012               [Page 4]


Internet-Draft                  RWS-DNRD                      March 2012


      'contact'- Contact record for a particular entity.  This includes
      contact name, organization, address, phone, email, etc.

      'host' - information about an Internet Host.  This includes server
      name, ipv4 or ipv6 address, sponsoring registrar, etc.

      'registrar' - information about an registrar, specifically the
      sponsoring registrar.  This includes registrar name, address,
      contact information, etc.

3.1.  Domain

   Queries for information about domain names are of the form /domain/
   example.tld/... where the path segment following 'domain' is an
   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:

      'registration' - for the registration data associated with the
      domain name including references to contacts and registrar, but
      not the actual contact information.

      'contacts' - contact information for the domain.

      'registrar' - contact information of the sponsoring registrar of
      the domain name.

   Optionally, specific type of contact information may be further
   targeted by following that path segment with a type.  What types of
   contacts a registry supports is for each registry policy to define.
   Examples of types of contacts typically supported are:

      registrant - contact information for the registrant

      admin - administrative contact information

      tech - technical contact information

      billing - billing contact information

   Finally, when no path segment follows the domain name, the semantics
   of the query are that both registration, contact, and registrar
   information are to be returned.

   Here are some example queries:

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




Sheng, et al.          Expires September 13, 2012               [Page 5]


Internet-Draft                  RWS-DNRD                      March 2012


      /domain/example.tld/ - returns all of example.tld's information.
      This includes registration, contact, host, and sponsoring
      registrar information.

      /domain/example.tld/registration - query for example.tld's
      registration information.  It will return the registration record
      with references to the contacts, registrar, name servers, and
      hosts.  But it would not return the actual information for those
      data objects.

      /domain/example.tld/contacts - returns all the contact information
      fordomain example.tld.

      /domain/example.tld/contacts/registrant - returns only the
      registrant information for domain example.tld.

      /domain/example.tld/contacts/tech - returns only the technical
      contact's information for domain example.tld.

      /domain/example.tld/registrar - returns the sponsoring registrar's
      contact information for domain example.tld.

3.2.  Contacts

   Queries for information about contacts are of the form /contact/
   contact-id/... where the contact-id is the id that the registry or
   registrar, as the case may be, uses to uniquely identify the contact.
   Path segments following the domain name can target specific
   information associated with the domain name in the following way:

   Here are some example queries:

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

      /contact/CNT-2222/ - queries the registrar or registry for contact
      id CNT-2222.

3.3.  Hosts

   Queries for information about hosts (or nameservers) are of the form
   /host/XXX/... where the path segment following 'host' is either a
   hostname [RFC1123], IPv4 [RFC0791] or IPv6 [RFC5952] address of the
   hostname.

   Here are some example queries:

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




Sheng, et al.          Expires September 13, 2012               [Page 6]


Internet-Draft                  RWS-DNRD                      March 2012


      /host/192.0.2.0/ - queries for host name with IPv4 address.

      /host/ns.example.tld/ - queries for host name ns.example.tld.

3.4.  Registrars

   Queries for information about registrars are of the form /registrar/
   XXX/... where the path segment following 'registrar' SHOULD be the
   the full name of the registrar (including punctuation, "Inc.", etc.)
   or its assigned ID.

   Here are some example queries:

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

      /registrar/"Network Solutions, LLC"/ - query the registrar names
      "Network Solutions.  LLC"

      /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
   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.

   Possible response formats and their signaling methods include:

      XML (default) - application/xml

      JSON - application/json

      HTML - text/html

      plain text - text/plain


4.  The Response

   The root element for a RWS-DNRD response is <rws>.  This element
   contains one <result> element, and one <addtional> element, that are



Sheng, et al.          Expires September 13, 2012               [Page 7]


Internet-Draft                  RWS-DNRD                      March 2012


   explained in the following section.

   Example of root element object:


   <?xml version="1.0" encoding="UTF-8"?>
   <rws:rws xmlns:rws="urn:ietf:params:xml:ns:rws-1.0"
       ...
       <rws:result>
       ...
       </rws:result>
       <rws:additional>
       ...
       </rws:additional>
       ...
   </rws:rws>

4.1.  Domain Names

   Example Query: http://whois.test/domain/example.test/

   Response:



<?xml version="1.0" encoding="UTF-8"?>
<rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
    <result>
        <domain:object
            xmlns:domain="urn:ietf:params:xml:ns:rwsDomain-1.0"
            href="/domain/example.test">
            <domain:name>example.test</domain:name>
            <domain:roid>9690-TEST</domain:roid>
            <domain:status s="clientHold"/>
            <domain:status s="clientRenewProhibited"/>
            <domain:status s="clientUpdateProhibited"/>
            <domain:registrant href="/contact/jd4447">
                jd4447
            </domain:registrant>
            <domain:contact type="admin" href="/contact/jd4447">
                jd4447
            </domain:contact>
            <domain:contact type="tech" href="/contact/jd4447">
                jd4447
            </domain:contact>
            <domain:ns>
                <domain:hostObj href="/host/ns1.example.test">
                    ns1.example.test



Sheng, et al.          Expires September 13, 2012               [Page 8]


Internet-Draft                  RWS-DNRD                      March 2012


                </domain:hostObj>
                <domain:hostObj href="/host/ns2.example.test">
                    ns2.example.test
                </domain:hostObj>
                <domain:hostObj href="/host/ns3.example.test">
                    ns3.example.test
                </domain:hostObj>
            </domain:ns>
            <domain:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </domain:registrar>
            <domain:registrar type="created" href="/registrar/reg-1289">
                reg-1289
            </domain:registrar>
            <domain:crDate>1992-07-26T09:10:56Z</domain:crDate>
            <domain:exDate>2019-01-21T10:11:18Z</domain:exDate>
        </domain:object>
    </result>
    <additional>
        <contact:object
            xmlns:contact="urn:ietf:params:xml:ns:rwsContact-1.0"
            href="/contact/jd4447">
            <contact:id>jd4447</contact:id>
            <contact:status s="clientDeleteProhibited"/>
            <contact:postalInfo type="int">
                <contact:name>John Doe</contact:name>
                <contact:org>Example Inc.</contact:org>
                <contact:addr>
                    <contact:street>123 Example Dr.</contact:street>
                    <contact:street>Suite 100</contact:street>
                    <contact:city>Redwood City</contact:city>
                    <contact:sp>CA</contact:sp>
                    <contact:pc>94063</contact:pc>
                    <contact:cc>US</contact:cc>
                </contact:addr>
            </contact:postalInfo>
            <contact:voice x="1234">+1.7035555555</contact:voice>
            <contact:fax>+1.7035555556</contact:fax>
            <contact:email>jdoe@example.com</contact:email>
            <contact:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </contact:registrar>
            <contact:crDate>1999-04-03T22:00:00.0Z</contact:crDate>
            <contact:upID>ClientX</contact:upID>
            <contact:upDate>1999-12-03T09:00:00.0Z</contact:upDate>
        </contact:object>
        <host:object xmlns:host="urn:ietf:params:xml:ns:rwsHost-1.0"
            href="/host/ns1.example.test">



Sheng, et al.          Expires September 13, 2012               [Page 9]


Internet-Draft                  RWS-DNRD                      March 2012


            <host:name>ns1.example.test</host:name>
            <host:status s="clientUpdateProhibited"/>
            <host:addr ip="v4">192.168.12.13</host:addr>
            <host:addr ip="v4">192.14.15.16</host:addr>
            <host:addr ip="v6">2001::A:B:C:1</host:addr>
            <host:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </host:registrar>
        </host:object>
        <host:object xmlns:host="urn:ietf:params:xml:ns:rwsHost-1.0"
            href="/host/ns2.example.test">
            <host:name>ns2.example.test</host:name>
            <host:status s="clientUpdateProhibited"/>
            <host:addr ip="v4">172.16.10</host:addr>
            <host:addr ip="v4">172.17.12</host:addr>
            <host:addr ip="v6">2001::B:C:D:1</host:addr>
            <host:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </host:registrar>
        </host:object>
        <host:object xmlns:host="urn:ietf:params:xml:ns:rwsHost-1.0"
            href="/host/ns3.example.test">
            <host:name>ns3.example.test</host:name>
            <host:status s="clientUpdateProhibited"/>
            <host:addr ip="v4">10.1.2.3</host:addr>
            <host:addr ip="v4">10.4.5.6</host:addr>
            <host:addr ip="v6">2001::C:D:E:1</host:addr>
            <host:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </host:registrar>
        </host:object>
        <registrar:object
            xmlns:registrar="urn:ietf:params:xml:ns:rwsRegistrar-1.0"
            href="/registrar/reg-793">
            <registrar:id>reg-793</registrar:id>
            <registrar:name>Example Registrar Inc.</registrar:name>
        </registrar:object>
        <registrar:object
            xmlns:registrar="urn:ietf:params:xml:ns:rwsRegistrar-1.0"
            href="/registrar/reg-1289">
            <registrar:id>reg-1289</registrar:id>
            <registrar:name>XYZ Corporation</registrar:name>
        </registrar:object>
    </additional>
</rws>


   Example Query: http://whois.test/domain/example.test/registration/



Sheng, et al.          Expires September 13, 2012              [Page 10]


Internet-Draft                  RWS-DNRD                      March 2012


   Response:



<?xml version="1.0" encoding="UTF-8"?>
<rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
    <result>
        <domain:object
            xmlns:domain="urn:ietf:params:xml:ns:rwsDomain-1.0"
            href="/domain/example.test">
            <domain:name>example.test</domain:name>
            <domain:roid>9690-TEST</domain:roid>
            <domain:status s="clientHold"/>
            <domain:status s="clientRenewProhibited"/>
            <domain:status s="clientUpdateProhibited"/>
            <domain:registrant href="/contact/jd4447">
                jd4447
            </domain:registrant>
            <domain:contact type="admin" href="/contact/jd4447">
                jd4447
            </domain:contact>
            <domain:contact type="tech" href="/contact/jd4447">
                jd4447
            </domain:contact>
            <domain:ns>
                <domain:hostObj href="/host/ns1.example.test">
                    ns1.example.test
                </domain:hostObj>
                <domain:hostObj href="/host/ns2.example.test">
                    ns2.example.test
                </domain:hostObj>
                <domain:hostObj href="/host/ns3.example.test">
                    ns3.example.test
                </domain:hostObj>
            </domain:ns>
            <domain:registrar type="sponsor" href="/registrar/reg-793">
                reg-793
            </domain:registrar>
            <domain:registrar type="created" href="/registrar/reg-1289">
                reg-1289
            </domain:registrar>
            <domain:crDate>1992-07-26T09:10:56Z</domain:crDate>
            <domain:exDate>2019-01-21T10:11:18Z</domain:exDate>
        </domain:object>
    </result>
</rws>





Sheng, et al.          Expires September 13, 2012              [Page 11]


Internet-Draft                  RWS-DNRD                      March 2012


   Example Query: http://whois.test/domain/example.test/contacts/

   Response:

   TBD.

   Example Query:
   http://whois.test/domain/example.test/contacts/registrant/

   Response:

   TBD.

   Example Query: http://whois.test/domain/example.test/registrar/

   Response:

   TBD.

4.2.  Contacts

   Example Query: http://whois.test/contact/jd4447/

   Response:



























Sheng, et al.          Expires September 13, 2012              [Page 12]


Internet-Draft                  RWS-DNRD                      March 2012


   <?xml version="1.0" encoding="UTF-8"?>
   <rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
       <result>
           <contact:object
               xmlns:contact="urn:ietf:params:xml:ns:rwsContact-1.0"
               href="/contact/jd4447">
               <contact:id>jd4447</contact:id>
               <contact:status s="clientDeleteProhibited"/>
               <contact:postalInfo type="int">
                   <contact:name>John Doe</contact:name>
                   <contact:org>Example Inc.</contact:org>
                   <contact:addr>
                       <contact:street>123 Example Dr.</contact:street>
                       <contact:street>Suite 100</contact:street>
                       <contact:city>Redwood City</contact:city>
                       <contact:sp>CA</contact:sp>
                       <contact:pc>94063</contact:pc>
                       <contact:cc>US</contact:cc>
                   </contact:addr>
               </contact:postalInfo>
               <contact:voice x="1234">+1.7035555555</contact:voice>
               <contact:fax>+1.7035555556</contact:fax>
               <contact:email>jdoe@example.com</contact:email>
               <contact:registrar href="/registrar/reg-793">
                   reg-793
               </contact:registrar>
               <contact:crDate>1999-04-03T22:00:00.0Z</contact:crDate>
               <contact:upDate>1999-12-03T09:00:00.0Z</contact:upDate>
           </contact:object>
       </result>
       <additional>
           <registrar:object
               xmlns:registrar="urn:ietf:params:xml:ns:rwsRegistrar-1.0"
               href="/registrar/reg-793">
               <registrar:id>reg-793</registrar:id>
               <registrar:name>Example Registrar Inc.</registrar:name>
           </registrar:object>
       </additional>
   </rws>


   Example Query: http://whois.test/contact/jd4447/registration/

   Response:







Sheng, et al.          Expires September 13, 2012              [Page 13]


Internet-Draft                  RWS-DNRD                      March 2012


   <?xml version="1.0" encoding="UTF-8"?>
   <rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
       <result>
           <contact:object
               xmlns:contact="urn:ietf:params:xml:ns:rwsContact-1.0"
               href="/contact/jd4447">
               <contact:id>jd4447</contact:id>
               <contact:status s="clientDeleteProhibited"/>
               <contact:postalInfo type="int">
                   <contact:name>John Doe</contact:name>
                   <contact:org>Example Inc.</contact:org>
                   <contact:addr>
                       <contact:street>123 Example Dr.</contact:street>
                       <contact:street>Suite 100</contact:street>
                       <contact:city>Redwood City</contact:city>
                       <contact:sp>CA</contact:sp>
                       <contact:pc>94063</contact:pc>
                       <contact:cc>US</contact:cc>
                   </contact:addr>
               </contact:postalInfo>
               <contact:voice x="1234">+1.7035555555</contact:voice>
               <contact:fax>+1.7035555556</contact:fax>
               <contact:email>jdoe@example.com</contact:email>
               <contact:registrar href="/registrar/reg-793">
                   reg-793
               </contact:registrar>
               <contact:crDate>1999-04-03T22:00:00.0Z</contact:crDate>
               <contact:upDate>1999-12-03T09:00:00.0Z</contact:upDate>
           </contact:object>
       </result>
   </rws>


   Example Query: http://whois.test/contact/jd4447/registrar/

   Response:

   TBD.

4.3.  Host Names

   Example Query: http://whois.test/host/ns1.example.test/

   Response:







Sheng, et al.          Expires September 13, 2012              [Page 14]


Internet-Draft                  RWS-DNRD                      March 2012


   <?xml version="1.0" encoding="UTF-8"?>
   <rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
       <result>
           <host:object xmlns:host="urn:ietf:params:xml:ns:rwsHost-1.0"
               href="/host/ns1.example.test">
               <host:name>ns1.example.test</host:name>
               <host:status s="clientUpdateProhibited"/>
               <host:addr ip="v4">192.168.12.13</host:addr>
               <host:addr ip="v4">192.14.15.16</host:addr>
               <host:addr ip="v6">2001::A:B:C:1</host:addr>
               <host:registrar type="sponsor" href="/registrar/reg-793">
                   reg-793
               </host:registrar>
           </host:object>
       </result>
       <additional>
           <registrar:object
               xmlns:registrar="urn:ietf:params:xml:ns:rwsRegistrar-1.0"
               href="/registrar/reg-793">
               <registrar:id>reg-793</registrar:id>
               <registrar:name>Example Registrar Inc.</registrar:name>
           </registrar:object>
       </additional>
   </rws>


   Example Query: http://whois.test/host/ns1.example.test/registration/

   Response:



   <?xml version="1.0" encoding="UTF-8"?>
   <rws xmlns="urn:ietf:params:xml:ns:rws-1.0">
       <result>
           <host:object xmlns:host="urn:ietf:params:xml:ns:rwsHost-1.0"
               href="/host/ns1.example.test">
               <host:name>ns1.example.test</host:name>
               <host:status s="clientUpdateProhibited"/>
               <host:addr ip="v4">192.168.12.13</host:addr>
               <host:addr ip="v4">192.14.15.16</host:addr>
               <host:addr ip="v6">2001::A:B:C:1</host:addr>
               <host:registrar type="sponsor" href="/registrar/reg-793">
                   reg-793
               </host:registrar>
           </host:object>
       </result>
   </rws>



Sheng, et al.          Expires September 13, 2012              [Page 15]


Internet-Draft                  RWS-DNRD                      March 2012


   Example Query: http://whois.test/host/ns1.example.test/registrar/

   Response:

   TBD.

4.4.  Registrars

   TBD


5.  Error Codes

   In compliance with the REST paradigm any error information is
   returned in the form of a standard HTTP response with an HTTP status
   code describing the error and a text/plain body message describing
   the exception causing the error response.  In this version we are
   using only standard HTTP codes
   (http://www.iana.org/assignments/http-status-codes).

   [[ Define specialized error codes. ]]


6.  Formal XML Syntax

   The formal syntax presented here is a complete schema representation
   suitable for automated validation of an XML instance.  It is based on
   the object schemas from the Extension Provisioning Protocol (EPP), by
   Scott Hollenbeck.  It references and includes the following EPP
   schemas:

      [RFC5730] - Extensible Provisioning Protocol (EPP)

      [RFC5731] - Extensible Provisioning Protocol (EPP) Domain Name
      Mapping

      [RFC5732] - Extensible Provisioning Protocol (EPP) Host Mapping

      [RFC5733] - Extensible Provisioning Protocol (EPP) Contact Mapping

   To represent objects, the <result> section will contain exactly one
   <object> element, under a specific namespace that describes the
   object type.  The object element will also contain an "href" property
   which can be used to verify it against the query.

   Objects in the result element can refer to other objects, i.e.: a
   domain object with multiple host object associations, contacts, etc.
   In order for the client to obtain all the information needed about



Sheng, et al.          Expires September 13, 2012              [Page 16]


Internet-Draft                  RWS-DNRD                      March 2012


   the queried object, additional objects can be described within the
   <additional> section.  Only objects referenced in the <object>
   element from the <result> section are allowed in the <additional>
   section.

   Server implementations can opt not to return the full object, but
   instead define an empty <object> element with an appropriate "href"
   property.  This enables the client to retrieve the additional objects
   from the server if needed.

6.1.  Contact XML Schema

   TBD

6.2.  Domain Name XML Schema

   TBD

6.3.  Host XML Schema

   TBD

6.4.  Registrar XML Schema

   TBD

6.5.  RWS XML Schema

   TBD


7.  Internationalization Considerations

7.1.  Considerations for Querying IDNs

   Three possibilities exist on how to query IDNs:

      U-label only - in this case an U-label is entered as part of the
      query.  For example: /domain/"U+82F1""U+96C4".test

      A-label only - in this case the U-label is first converted to its
      corresponding A-label before submitted to the server.  In the
      example above, the U-label would be /domain/xn--dj1az91b.test
      before it is submitted to the RWS-DNRD.

      IRI -> URI conversion - in this case the IRI (which contains the
      U-label) is converted to URI according to [[RFC3987]] before
      submitted to the server.  In the example above, the query becomes



Sheng, et al.          Expires September 13, 2012              [Page 17]


Internet-Draft                  RWS-DNRD                      March 2012


      /domain/%E8%8B%B1%E9%9B%84.test

7.2.  Considerations for Display of Internationalized Registration Data

   Information published in RWS-DNRD is represented in XML, which
   provides native support for encoding information using the Unicode
   character set and its more compact representations including UTF-8.
   Conformant XML processors recognize both UTF-8 and UTF-16.  Though
   use of UTF-8 is preferred, XML includes provisions to identify and
   use other character encodings through use of an "encoding" attribute
   in an <?xml?> declaration.

7.3.  Considerations for Indicating Language/scripts in Responses

   The RWS-DNRD proposed by this document supports internationalized
   registration data, responses of a RWS-DNRD server may contain data in
   any languages/scripts.  Although the internationalized registration
   data of a RWS-DNRD response can be correctly displayed, users will
   still be confused when reading the data in a language which t hey are
   not familiar.  So if the response of the RWS-DNRD need to contain
   information to indicate the language/scripts the responses is in.
   This is also one of the recommendations / requirements from the ICANN
   Internationalized Registration Data Working Group Final Report
   [IRD-WG].

   In order to meet the above requirement, one additional data element
   needs to be added to allow for the association of the IRD response to
   a language/script identifier.  The identifiers SHALL be structured as
   documented in [RFC5646].

   For example,

   <?xml version="1.0" encoding="UTF-8"?>
   <rws:rws xmlns:rws="urn:ietf:params:xml:ns:rws-1.0"
       <rws:language>
       zh
       </rws:language>
       <rws:result>
       ...
       </rws:result>
   </rws:rws>

   The above solution can only support one language within one response.
   If multiple languages need to be supported by one response, one
   additional attribute of data element might be considered to be added
   to allow for association of the value of a data element to an
   internationalized language identifier.




Sheng, et al.          Expires September 13, 2012              [Page 18]


Internet-Draft                  RWS-DNRD                      March 2012


   Further discussions is needed on this topic.


8.  IANA Considerations

   TBD


9.  Security Considerations

   TBD

9.1.  URIs and IRIs

   RWS-DNRD implementations use URIs and IRIs.  See Section 7 of
   [RFC3986] and Section 8 of [RFC3987] for security considerations
   related to their handling and use.


10.  Acknowledgments

   Parts of this document are based on EPP [RFC5730] and related RFCs by
   Scott Hollenbeck.

   The authors would like to acknowledge the following individuals for
   their input: Andy Newton, Andrew Sullivan, Dave Piscitello and James
   Galvin.


11.  Change History

11.1.  Changes from version 00 to 01

   1.  Added two co-authors.

   2.  Modified the query structure to resemble RIR query structures

   3.  Added considerations for the query of Internationalized Domain
       Names (IDNs)

   4.  Added considerations for the display of Internationalized
       Registration Data.

   5.  Updated the data schema.

   6.  Fixed some typographical errors and omissions.





Sheng, et al.          Expires September 13, 2012              [Page 19]


Internet-Draft                  RWS-DNRD                      March 2012


12.  References

12.1.  Normative References

   [REST]     Fielding, R. and R. Taylor, "Principled Design of the
              Modern Web Architecture", ACM Transactions on Internet
              Technology Vol. 2, No. 2, May 2002.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC5646]  Phillips, A. and M. Davis, "Tags for Identifying
              Languages", BCP 47, RFC 5646, September 2009.

   [RFC5730]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, August 2009.

   [RFC5731]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Domain Name Mapping", STD 69, RFC 5731, August 2009.

   [RFC5732]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Host Mapping", STD 69, RFC 5732, August 2009.

   [RFC5733]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Contact Mapping", STD 69, RFC 5733, August 2009.

   [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
              Address Text Representation", RFC 5952, August 2010.

12.2.  Informative References

   [I-D.newton-et-al-weirds-rir-json-response]
              Newton, A., Ranjbar, K., Servin, A., and B. Ellacott,
              "JSON Responses to RESTful URL Queries for RIRs",
              draft-newton-et-al-weirds-rir-json-response-01 (work in
              progress), March 2012.

   [I-D.newton-et-al-weirds-rir-query]
              Newton, A., Ranjbar, K., Servin, A., and B. Ellacott, "A
              Uniform RESTful URL Query Pattern for RIRs",
              draft-newton-et-al-weirds-rir-query-01 (work in progress),
              March 2012.

   [IRD-WG]   ICANN, "The Final Report of the Internationalized
              Registration Data Working Group", February 2012.

   [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791,



Sheng, et al.          Expires September 13, 2012              [Page 20]


Internet-Draft                  RWS-DNRD                      March 2012


              September 1981.

   [RFC1123]  Braden, R., "Requirements for Internet Hosts - Application
              and Support", STD 3, RFC 1123, October 1989.

   [RFC3707]  Newton, A., "Cross Registry Internet Service Protocol
              (CRISP) Requirements", RFC 3707, February 2004.

   [RFC3912]  Daigle, L., "WHOIS Protocol Specification", RFC 3912,
              September 2004.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC3987]  Duerst, M. and M. Suignard, "Internationalized Resource
              Identifiers (IRIs)", RFC 3987, January 2005.

   [RFC4627]  Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.


Authors' Addresses

   Steve Sheng
   Internet Corporation for Assigned Names and Numbers
   4676 Admiralty Way, Suite 330
   Marina del Rey, CA  90292
   United States of America

   Phone: +1.310.823.9358
   Email: steve.sheng@icann.org


   Francisco Arias
   Internet Corporation for Assigned Names and Numbers
   4676 Admiralty Way, Suite 330
   Marina del Rey, CA  90292
   United States of America

   Phone: +1.310.823.9358
   Email: francisco.arias@icann.org









Sheng, et al.          Expires September 13, 2012              [Page 21]


Internet-Draft                  RWS-DNRD                      March 2012


   Francisco Obispo
   Internet Systems Consortium
   950 Charter St
   Redwood City, CA  94063
   United States of America

   Phone: +1.650.423.1374
   Email: fobispo@isc.org


   Ning Kong
   China Internet Network Information Center
   4 South 4th Street, Zhongguancun, Haidian District
   Beijing  100190
   China

   Phone: +86 10 5881 3147
   Email: nkong@cnnic.cn

































Sheng, et al.          Expires September 13, 2012              [Page 22]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/