[Search] [txt|xml|pdf|bibtex] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02                                                      
Network Working Group                                          A. Newton
Internet-Draft                                                      ARIN
Intended status: Standards Track                              K. Ranjbar
Expires: January 13, 2013                                       RIPE NCC
                                                               A. Servin
                                                                  LACNIC
                                                             B. Ellacott
                                                                   APNIC
                                                           July 12, 2012


             JSON Responses to RESTful URL Queries for RIRs
             draft-newton-et-al-weirds-rir-json-response-02

Abstract

   This document describes responses in the JSON format to the RESTful
   queries described in draft-newton-et-al-weirds-rir-query.

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 January 13, 2013.

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



Newton, et al.          Expires January 13, 2013                [Page 1]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Congruence With Other Registry Data Access Protocols . . . . .  4
   3.  Responses  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     3.1.  IP Networks  . . . . . . . . . . . . . . . . . . . . . . .  5
     3.2.  Autonomous Systems . . . . . . . . . . . . . . . . . . . .  8
     3.3.  Reverse DNS  . . . . . . . . . . . . . . . . . . . . . . . 10
   4.  The Entity Object  . . . . . . . . . . . . . . . . . . . . . . 13
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15
   6.  Normative References . . . . . . . . . . . . . . . . . . . . . 16
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17



































Newton, et al.          Expires January 13, 2013                [Page 2]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


1.  Introduction

   The Regional Internet Registries (RIRs) have begun experimenting with
   RESTful web services for access to Whois data.  RIR-QUERY
   [I-D.newton-et-al-weirds-rir-query] presents uniform patterns which
   may be used to contruct URLs for accessing data from these RESTful
   web services.  This document describes responses in the JSON
   [RFC4627] serialization format to the query URLs in RIR-QUERY.

   As this document describes responses returned in JSON [RFC4627]
   format, other documents may describe responses in other formats to
   the same URL queries.







































Newton, et al.          Expires January 13, 2013                [Page 3]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


2.  Congruence With Other Registry Data Access Protocols

   This document describes the URL patterns for a Number Resource
   Registry Data Access Protocol (NRRD-AP) and describes a Registry Data
   Access Protocol (RD-AP) adhering to
   [I-D.designteam-weirds-using-http], the intent being a specification
   for number resource registries useful and in the style similar to
   other registry access protocols, such as Domain Name Registry Access
   Protocols (DNRP-AP).

   Of specific note, the signalling for JSON, JSON naming scheme, and
   normalized references to other specifications are documented in
   [I-D.designteam-weirds-using-http].

   With specific regards to JSON format signalling, this document
   defines and registers the media type "application/nrrdap+json", and
   conformance to this specification is level 0.  The JSON value for to
   be used within the rdapConformance array is "nrrdap_level_0".

































Newton, et al.          Expires January 13, 2013                [Page 4]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


3.  Responses

   As specified in RIR-QUERY [I-D.newton-et-al-weirds-rir-query],
   queries for resources and information can be made for three types of
   information: 1) information about IP networks, 2) information about
   autonomous system numbers, and 3) information about reverse DNS
   delegations.  Queries for each of these three types can be
   constructed to target specific information:

   o  operator information (e.g. "/operator")

   o  contacts of the operator (e.g "/operator/contacts")

   o  specific types of contacts of the operator (e.g. "/operator/
      contacts/abuse")

   o  registration information about the networks, AS numbers, or DNS
      delegations (e.g. "/registration")

   o  all of the above (e.g. "/")

   Unless otherwise stated, data types of the values listed in this
   section are referenced in [I-D.designteam-weirds-using-http].

3.1.  IP Networks

   The following is an elided example of a JSON [RFC4627] response
   object to a query for both registration and operator information of
   an IP network


   {
     "network":
     {
       ...
     },
     "operator":
     {
       ...
     }
   }


                                 Figure 1

   The "network" member, which may be queried for directly as the
   registration information (i.e. "/registration") of the IP network is
   described below.



Newton, et al.          Expires January 13, 2013                [Page 5]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   The following is an example of the JSON object for the network
   registration information


   {
     "handle" : "XXXX-RIR",
     "startAddress" : "10.0.0.0",
     "endAddress" : "10.0.0.255",
     "ipVersion" : 4,
     "name": "NET-RTR-1",
     "description" : [ "A network used for routing" ],
     "type" : "DIRECT ALLOCATION",
     "country" : "AU",
     "parentHandle" : "YYYY-RIR",
     "remarks" : [
       "she sells seas shells",
       "down by the seashore"
     ],
     "uris" : [
       {
         "type" : "source",
         "uri" : "http://whois-rws.net/network/xxxx"
       },
       {
         "type" : "parent",
         "uri" : "http://whois-rws.net/network/yyyy"
       },
       {
         "type" : "held",
         "uri" : "http://example.net/location/xxxx"
       }
     ],
     "registrationDate" : "20110509",
     "lastChangedDate" : "20110509",
     "lastChangedBy" : "joe@bob.com"
   }


   The following is a description of the members of this object:

   handle  -- a string representing an RIR unique identifier of the
      network registration

   startAddress  -- the starting IP address of the network, either IPv4
      or IPv6






Newton, et al.          Expires January 13, 2013                [Page 6]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   endAddress  -- the ending IP address of the network, either IPv4 or
      IPv6

   ipVersion  -- an integer signifying the IP protocol version of the
      network: 4 signifying an IPv4 network, 6 signifing an IPv6 network

   name  -- an identifier assigned to the network registration by the
      registration holder

   description  -- an array of strings containing descriptive text about
      the network registration

   type  -- a string containing an RIR specific classification of the
      network

   country  -- a string containing the name of the 2 character country
      code of the network

   parentHandle  -- a string containing an RIR unique identifier of the
      parent network of this network registration

   The members "remarks", "uris", "registrationDate", "lastChangedDate",
   and "lastChangedBy" take the same form of the members of the same
   name of the entity object (Section 4).

   The "operator" member of Figure 1, which maybe queried for directly
   using the "/operator" path, is described below.
























Newton, et al.          Expires January 13, 2013                [Page 7]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   The following is an elided example of a JSON response object for
   operator information


   {
     "entity":
     {
       ...
     },
     "contacts":
     {
       "tech": [
         ...
       ],
       "admin": [
         ...
       ],
       "abuse": [
         ...
       ]
     }
   }


                                 Figure 2

   The "entity" member of Figure 2 is an object and is specified in
   Section 4.  The "contacts" member is an object containing three
   arrays: "tech", "admin", and "abuse".  Each of these arrays contains
   entities (Section 4).  That is, the "tech" array contains entity
   objects, each representing a tech contact, etc...

3.2.  Autonomous Systems

   An autonomous number query for both the registration and operator
   and/or contact information yields an object containing an "autnum"
   member and an "operator" member.  The "operator" member is as
   specified in Section 3.1.  Additionally, queries specifically for the
   operator and/or contact information take the same form as in
   Section 3.1.

   The "autnum" member mentioned above as well as queries directly for
   the registration information take the form of a JSON [RFC4627]
   object.







Newton, et al.          Expires January 13, 2013                [Page 8]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   The following is an example of a JSON object representing an autnum.


   {
     "handle" : "XXXX-RIR",
     "startAutnum" : "10",
     "endAutnum" : "15",
     "name": "AS-RTR-1",
     "description" : [ "AS for Exchange" ],
     "type" : "DIRECT ALLOCATION",
     "country": "AU",
     "remarks" : [
       "she sells seas shells",
       "down by the seashore"
     ],
     "uris" : [
       {
         "type" : "source",
         "uri" : "http://whois-rws.net/autnum/xxxx"
       },
       {
         "type" : "parent",
         "uri" : "http://whois-rws.net/autnum/yyyy"
       },
       {
         "type" : "held",
         "uri" : "http://example.net/location/xxxx"
       }
     ],
     "registrationDate" : "20110509",
     "lastChangedDate" : "20110509",
     "lastChangedBy" : "joe@bob.com"
   }


   The following is a description of the members of this object:

   handle  -- a string representing an RIR unique identifier of the
      autnum registration

   startAutnum  -- the starting number [RFC5396] in the block of
      autonomous system numbers

   endAutnum  -- the ending number [RFC5396] in the block of autonomous
      system numbers






Newton, et al.          Expires January 13, 2013                [Page 9]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   name  an identifier assigned to the autnum registration by the
      registration holder

   description  -- an array of strings containing descriptive text about
      the autnum registration

   type  -- a string containing an RIR specific classification of the
      autnum

   country  -- a string containing the name of the 2 character country
      code of the autnum

   The members "remarks", "uris", "registrationDate", "lastChangedDate",
   and "lastChangedBy" take the same form of the members of the same
   name of the entity object (Section 4).

3.3.  Reverse DNS

   A reverse DNS delegation query for both the registration and operator
   and/or contact information yields an object containing an "rdns"
   member and an "operator" member.  The "operator" member is as
   specified in Section 3.1.  Additionally, queries specifically for the
   operator and/or contact information take the same form as in
   Section 3.1.

   The "rdns" member mentioned above as well as queries directly for the
   reverse DNS information take the form of a JSON [RFC4627] object.
























Newton, et al.          Expires January 13, 2013               [Page 10]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   The following is an example of a JSON object representing an reverse
   DNS delegation.


   {
     "handle" : "XXXX-RIR",
     "name" : "192.in-addr.arpa",
     "nameServers" : [ "ns1.rir.net", "ns2.rir.net" ],
     "delegationKeys" : [
       {
         "algorithm": 7,
         "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
         "digestType" : 1,
         "keyTag" : 53814
       }
     ],
     "remarks" : [
       "she sells seas shells",
       "down by the seashore"
     ],
     "uris" : [
       {
         "type" : "source",
         "uri" : "http://whois-rws.net/network/xxxx"
       },
       {
         "type" : "parent",
         "uri" : "http://whois-rws.net/network/yyyy"
       },
       {
         "type" : "held",
         "uri" : "http://example.net/location/xxxx"
       }
     ],
     "registrationDate" : "20110509",
     "lastChangedDate" : "20110509",
     "lastChangedBy" : "joe@bob.com"
   }


   The following is a description of the members of this object:

   handle  -- a string representing an RIR unique identifier of the
      reverse DNS delegation







Newton, et al.          Expires January 13, 2013               [Page 11]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   name  -- a string denoting the DNS zone name, which is a domain name

   nameservers  -- an array of strings, each being a fully qualified DNS
      name of a namesever

   delegationKeys  -- an array of objects, each with the following
      members:

      algorithm  -- an integer as specified by the algorithm field of a
         DNS DS record as specified by RFC 4034 [RFC4034] in
         presentation format

      digest  -- an string as specified by the digest field of a DNS DS
         record as specified by RFC 4034 in presentation format

      digestType  -- an integer as specified by the digest type field of
         a DNS DS record as specified by RFC 4034 in presetnation format

      keyTag  -- an integer as specified by the key tag field of a DNS
         DS record as specified by RFC 4034 in presentation format

   The members "remarks", "uris", "registrationDate", "lastChangedDate",
   and "lastChangedBy" take the same form of the members of the same
   name of the entity object (Section 4).



























Newton, et al.          Expires January 13, 2013               [Page 12]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


4.  The Entity Object

   Throughout this document there is a need to represent the identity
   and contact information of organizations, corporations, governments,
   non-profits, clubs, individual persons, and informal groups of
   people.  All of these representations are so similar that it is best
   to represent them in JSON [RFC4627] with one construct, the entity
   object, to aid in the re-use of code by implementers.

   The following is an example of an entity:


       {
         "handle" : "XXXX-RIR",
         "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
         "postalAddress" : [
           "123 Maple Ave",
           "Suite 90001",
           "Vancouver",
           "BC",
           "12393"
         ],
         "emails" : [ "joe@bob.com", "bob@joe.com" ],
         "phones" : {
           "office" : [ "999-999-999-99", "111-111-111-11" ],
           "fax" : [ "222-222-222-22" ],
           "mobile" : [ "333-333-333-33" ]
         },
         "remarks" : [
           "she sells seas shells",
           "down by the seashore"
         ],
         "uris" : [
         {
           "type" : "source",
           "uri" : "http://whois-rws.net/contact/xxxx"
         },
         {
           "type" : "held",
           "uri" : "http://example.net/location/xxxx"
         }
         ],
         "registrationDate" : "20110509",
         "lastChangedDate" : "20110509",
         "lastChangedBy" : "joe@bob.com"
       }





Newton, et al.          Expires January 13, 2013               [Page 13]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


   This object as the following members.

   handle  -- a string representing an RIR unique identifier of the
      entity

   names  -- an array of strings, each signifying the name of the entity

   postalAddress  -- an array of string, each representing a line in a
      postal address.

   emails  -- an array of strings, each containing an email address for
      the entity

   phones  -- an object containg telephone information associated with
      the entity, with the following members:

      office  -- an array of strings, each being a telephone number

      fax  -- an array of strings, each being a telephone number

      mobile  -- an array of strings, each being a telephone number

   remarks  -- an array of strings, each containing comments about the
      entity

   uris  -- an array of objects, each object having the following
      members:

      type  -- a string denoting the application type of the "uri" value

      uri  -- a string containing a URI [RFC3986]

   registrationDate  -- a string containing the date the entity was
      registered

   lastChangedDate  -- a string containing the date of last change made
      to the entity

   lastChangedBy  -- a string containing an identifier of the party
      responsible for the last change made to the entity registration











Newton, et al.          Expires January 13, 2013               [Page 14]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


5.  IANA Considerations

   This specification registers the "application/nrrdap+json" media
   type.

      Type name: application

      Subtype name: nrrdap+json

      Required parameters: n/a

      Optional parameters: level

      Encoding considerations: n/a

      Security considerations: n/a

      Interoperability considerations: n/a

      Published specification: [[ this document ]]

      Applications that use this media type: RESTful Whois applications

      Additional information: n/a

      Person & email address to contact for further information: Andy
      Newton &andy@hxr.us&

      Intended usage: COMMON

      Restrictions on usage: none

      Author: Andy Newton

      Change controller: IETF
















Newton, et al.          Expires January 13, 2013               [Page 15]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


6.  Normative References

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

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

   [RFC4034]  Arends, R., Austein, R., Larson, M., Massey, D., and S.
              Rose, "Resource Records for the DNS Security Extensions",
              RFC 4034, March 2005.

   [RFC5396]  Huston, G. and G. Michaelson, "Textual Representation of
              Autonomous System (AS) Numbers", RFC 5396, December 2008.

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

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

   [I-D.designteam-weirds-using-http]
              Newton, A., Ranjbar, K., Servin, A., Ellacott, B.,
              Hollenbeck, S., Sheng, S., Arias, F., Kong, N., and F.
              Obispo, "Using HTTP for RESTful Whois Services by Internet
              Registries", draft-designteam-weirds-using-http-01 (work
              in progress), May 2012.



















Newton, et al.          Expires January 13, 2013               [Page 16]


Internet-Draft         RIR RESTful JSON RESPONSES              July 2012


Authors' Addresses

   Andrew Lee Newton
   American Registry for Internet Numbers
   3635 Concorde Parkway
   Chantilly, VA  20151
   US

   Email: andy@arin.net
   URI:   http://www.arin.net


   Kaveh Ranjbar
   RIPE Network Coordination Centre
   Singel 258
   Amsterdam  1016AB
   NL

   Email: kranjbar@ripe.net
   URI:   http://www.ripe.net


   Arturo L. Servin
   Latin American and Caribbean Internet Address Registry
   Rambla Republica de Mexico 6125
   Montevideo  11300
   UY

   Email: aservin@lacnic.net
   URI:   http://www.lacnic.net


   Byron J. Ellacott
   Asia Pacific Network Information Center
   6 Cordelia Street
   South Brisbane  QLD 4101
   Australia

   Email: bje@apnic.net
   URI:   http://www.apnic.net











Newton, et al.          Expires January 13, 2013               [Page 17]