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

              A Uniform RESTful URL Query Pattern for RIRs
                 draft-newton-et-al-weirds-rir-query-01
                 draft-newton-et-al-weirds-rir-query-02

Abstract

   This document describes uniform patterns for which to construct HTTP
   URLs that may be used to retreive information from Regional Internet
   Registries (RIRs) using "RESTful" web access patterns.

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 12, 2012. 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
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Design Intents . . . . . . . . . . . . . . . . . . .  Congruence With Other Registry Data Access Protocols . . . . .  4
   3.  Path Specification . . . . . . . . . . . . . . . . . . . . . .  5
     3.1.  IP Networks  . . . . . . . . . . . . . . . . . . . . . . .  5
     3.2.  Autonomous Systems . . . . . . . . . . . . . . . . . . . .  7
     3.3.  Reverse DNS  . . . . . . . . . . . . . . . . . . . . . . .  8
   4.  Query Paramaters . . . . . . . . . . . . . . . . . . . . . . .  9
   5.  Normative References . . . . . . . . . . . . . . . . . . . . . 10  9
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 10

1.  Introduction

   The Regional Internet Registries (RIRs) have begun experimenting with
   RESTful web services for access to Whois data.  This document
   presents uniform patterns which may be used to contruct URLs for
   accessing data from these RESTful web services.

   The patterns described in this document purposefully do not encompass
   all of the methods employed in the Whois and RESTful web services of
   all of the RIRs.  The intent of the patterns described here are to
   enable lookups of networks by IP address, autonomous system numbers
   by number, and reverse DNS meta-data reverse DNS domain labels.  It
   is envisioned that each RIR will continue to maintain NICNAME/WHOIS
   and/or RESTful web services specific to their needs and those of
   their constituencies, and the information retreived through the
   patterns described here may reference such services.

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

   This document does not describe the results or entities returned from
   issuing the described URLs with an HTTP GET.  It is envisioned that
   other documents will describe these entities in various serialization
   formats, such as XML and JSON.

   Additionally, resource management, provisioning and update functions
   are out of scope for this document.  RIRs have various and divergent
   methods covering these functions, and it is unlikely a uniform
   approach for these functions will ever be possible.

   And while HTTP contains mechanisms for servers to authenticate
   clients and clients to authenticate servers, from which authorization
   schemes may be built, both authentication of clients and servers and
   authorization for access to data are out-of-scope of this document.
   In general, these matters require "policy" and are not the domain of
   technical standards bodies.

2.  Design Intents

   There are a few design criteria this document attempts to support.

   First, each query is meant to return either zero or one result.  Congruence With
   the maximum upper bound being set to one, the issuance of redirects
   is simplified to the known Other Registry Data Access Protocols

   This document model used by HTTP [RFC2616].
   Should a result contain more than one result, some of which are
   better served by other servers, describes the redirection model becomes much
   more complicated.

   Second, response formats are not specified in this document as 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 is to leave room for multiple format types.

   Third, HTTP offers being a specification
   for number of transport protocol mechanisms not
   described further in this document.  Operators are able to make use
   of these mechanisms according to their local policy, including cache
   control, authorization, compression, resource registries useful and redirection.  HTTP also
   benefits from widespread investment in scalability, reliability, and
   performance the style similar to
   other registry access protocols, such as Domain Name Registry Access
   Protocols (DNRP-AP).

3.  Path Specification

   The uniform patterns start with a base URL [RFC3986] specified by
   each RIR 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://example.com/... or http://example.com/restful-whois/... ).

   The resource type path segments are:

   o  'ip' : IP networks and associated data referenced using either an
      IPv4 or IPv6 address.

   o  'autnum' : Autonomous system registrations and associated data
      referenced using an AS Plain autonomous system number.

   o  'rdns' : Reverse DNS information and associated data referenced
      using a fully-qualified domain name.

3.1.  IP Networks

   Queries for information about IP networks are of the form /ip/XXX/...
   or /ip/XXX/YY/... where the path segment following 'ip' is either an
   IPv4 [RFC0791] or IPv6 [RFC5952] address (i.e.  XXX) or an IPv4 or
   IPv6 CIDR [RFC4632] notation address block (i.e.  XXX/YY).
   Semantically, the simpler form using the address can be thought of as
   a CIDR block with a length of 32 for IPv4 and a length of 128 for
   IPv6.  A given specific address or CIDR may fall within multiple IP
   networks in a hierarchy of networks, therefore this query targets the
   "most-specific" or lowest IP network which completely encompasses it
   in a hierarchy of IP networks.

   Path segments following the IP address or CIDR notation target
   specific information associated with the targetted IP network in the
   following way:

   o  'registration' : The query is for the network registration data.

   o  'operator' : The query is for data about the network operator of
      the IP network.  The network operator is not always considered to
      be the end user or end site customer of the IP network, a
      distinction made in some cases.  For example, a residential
      Internet installation may be assigned IP addresses, but the
      provider from whom they receive Internet access is considered the
      network operator.  Another rule of thumb is that the network
      operator is the entity contacted to coordinate network issues and
      has published contact information for this purpose, and operator
      information can be further decomposed into operator contact
      information, which is returned with the 'operator' query when not
      specifically targetted (see below).

   When no path segment follows the IP address, the semantics of the
   query are that both registration and operator information are to be
   returned.

   The following example URL [RFC3986] is a query for the IP network
   registrion information.

     http://example.com/somepath/ip/192.0.2.0/registration

   The following example URL is a query for the IP network registration
   information for the most specific IP network starting with 192.0.2.0
   and ending with 192.0.2.255.

     http://example.com/somepath/ip/192.0.2.0/24/registration

   The following example URL is a query for the network operator
   information of the most specific network containing 192.0.2.0

     http://example.com/somepath/ip/192.0.2.0/operator

   And this is an example URL for both the registration and operator
   information of the most specific network containing 192.0.2.0

     http://example.com/somepath/ip/192.0.2.0

   This is an example of a URL for both the registration and operator
   information of the most specific network containing 192.0.2.0/24.

     http://example.com/somepath/ip/192.0.2.0/24

   The contact information of an operator maybe specifically targetted
   by following it with a 'contacts' path segment.  And the type of
   contact information may be further targetted by following that path
   segment with a type.  The types are:

   o  tech

   o  admin

   o  abuse

   For example:

     /ip/192.0.2.0/operator/contacts

   returns all the contact information for the network operator of the
   most specific network containing IP address 192.0.2.0.

   And this path targets only the abuse contacts of that network
   operator.

     /ip/192.0.2.0/operator/contacts/abuse

3.2.  Autonomous Systems

   Queries for information regarding autonomous system number
   registrations are of the form /autnum/XXX/... where XXX is an
   autonomous system number [RFC5396].  In some registries, registration
   of autonomous system numbers is done on an individual number basis,
   while other registries may register blocks of autonomous system
   numbers.  The semantics of this query is such that if a number falls
   within a range of registered blocks, the target of the query is the
   block registration, and that individual number registrations are
   considered a block of numbers with a size of 1.

   For example, to find information on autonomous system number 65551,
   the following path would be used:

     /autnum/65551

   The autnum path segment may be followed by a 'registration' or
   'operator' path segment or no additional path segment, all of which
   follow the semantics above (Section 3.1).

3.3.  Reverse DNS

   Queries for reverse DNS information are of the form
   /rdns/XXXXXXXXX/... where XXXX is a fully-qualified domain name
   [RFC4343] in either the in-addr.arpa or ip6.arpa zones.

   For example, to find information on the zone serving the network
   192.0.2/24, the following path would be used:

     /rdns/2.0.192.in-addr.arpa

   The rdns path segment may be follwed by a 'registration' or
   'operator' path segment or no additional path segment, all of which
   follow the semantics in Section 3.1.

4.  Query Paramaters

   To overcome issues with misbehaving HTTP [RFC2616] cache
   infrastructure, clients may use the '__weirds__cachebust' query
   parameter with a random value of their choosing.  Servers MUST ignore
   this query parameter.

   The following is an example use of this parameter to retreive the
   abuse contacts associated with the most specific IP network with the
   address 192.0.2.0:

     /ip/192.0.2.0/operator/contacts/abuse?__weirds_cachebust=xyz123

   For all others, server SHOULD ignore unknown query parameters.

5.  Normative References

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

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

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

   [RFC4343]  Eastlake, D., "Domain Name System (DNS) Case Insensitivity
              Clarification", RFC 4343, January 2006.

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

   [RFC4632]  Fuller, V. and T. Li, "Classless Inter-domain Routing
              (CIDR): The Internet Address Assignment and Aggregation
              Plan", BCP 122, RFC 4632, August 2006.

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

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

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