draft-newton-et-al-weirds-rir-query-01.txt   draft-newton-et-al-weirds-rir-query-02.txt 
Network Working Group A. Newton Network Working Group A. Newton
Internet-Draft ARIN Internet-Draft ARIN
Intended status: Standards Track K. Ranjbar Intended status: Standards Track K. Ranjbar
Expires: September 12, 2012 RIPE NCC Expires: January 13, 2013 RIPE NCC
A. Servin A. Servin
LACNIC LACNIC
B. Ellacott B. Ellacott
APNIC APNIC
March 11, 2012 July 12, 2012
A Uniform RESTful URL Query Pattern for RIRs 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 Abstract
This document describes uniform patterns for which to construct HTTP This document describes uniform patterns for which to construct HTTP
URLs that may be used to retreive information from Regional Internet URLs that may be used to retreive information from Regional Internet
Registries (RIRs) using "RESTful" web access patterns. Registries (RIRs) using "RESTful" web access patterns.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 37 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 12, 2012. This Internet-Draft will expire on January 13, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Design Intents . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Congruence With Other Registry Data Access Protocols . . . . . 4
3. Path Specification . . . . . . . . . . . . . . . . . . . . . . 5 3. Path Specification . . . . . . . . . . . . . . . . . . . . . . 5
3.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 7 3.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 7
3.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 8 3.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 8
4. Query Paramaters . . . . . . . . . . . . . . . . . . . . . . . 9 4. Normative References . . . . . . . . . . . . . . . . . . . . . 9
5. Normative References . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
The Regional Internet Registries (RIRs) have begun experimenting with The Regional Internet Registries (RIRs) have begun experimenting with
RESTful web services for access to Whois data. This document RESTful web services for access to Whois data. This document
presents uniform patterns which may be used to contruct URLs for presents uniform patterns which may be used to contruct URLs for
accessing data from these RESTful web services. accessing data from these RESTful web services.
The patterns described in this document purposefully do not encompass 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 methods employed in the Whois and RESTful web services of
skipping to change at page 4, line 5 skipping to change at page 4, line 5
methods covering these functions, and it is unlikely a uniform methods covering these functions, and it is unlikely a uniform
approach for these functions will ever be possible. approach for these functions will ever be possible.
And while HTTP contains mechanisms for servers to authenticate And while HTTP contains mechanisms for servers to authenticate
clients and clients to authenticate servers, from which authorization clients and clients to authenticate servers, from which authorization
schemes may be built, both authentication of clients and servers and schemes may be built, both authentication of clients and servers and
authorization for access to data are out-of-scope of this document. authorization for access to data are out-of-scope of this document.
In general, these matters require "policy" and are not the domain of In general, these matters require "policy" and are not the domain of
technical standards bodies. technical standards bodies.
2. Design Intents 2. Congruence With Other Registry Data Access Protocols
There are a few design criteria this document attempts to support.
First, each query is meant to return either zero or one result. With
the maximum upper bound being set to one, the issuance of redirects
is simplified to the known document model used by HTTP [RFC2616].
Should a result contain more than one result, some of which are
better served by other servers, the redirection model becomes much
more complicated.
Second, response formats are not specified in this document as the
intent is to leave room for multiple format types.
Third, HTTP offers a number of transport protocol mechanisms not This document describes the URL patterns for a Number Resource
described further in this document. Operators are able to make use Registry Data Access Protocol (NRRD-AP) and describes a Registry Data
of these mechanisms according to their local policy, including cache Access Protocol (RD-AP) adhering to
control, authorization, compression, and redirection. HTTP also [I-D.designteam-weirds-using-http], the intent being a specification
benefits from widespread investment in scalability, reliability, and for number resource registries useful and in the style similar to
performance other registry access protocols, such as Domain Name Registry Access
Protocols (DNRP-AP).
3. Path Specification 3. Path Specification
The uniform patterns start with a base URL [RFC3986] specified by The uniform patterns start with a base URL [RFC3986] specified by
each RIR or any other service provider offering this service. The each RIR or any other service provider offering this service. The
base URL will be appended with resource type specific path segments. base URL will be appended with resource type specific path segments.
The base URL may contain its own path segments (e.g. The base URL may contain its own path segments (e.g.
http://example.com/... or http://example.com/restful-whois/... ). http://example.com/... or http://example.com/restful-whois/... ).
The resource type path segments are: The resource type path segments are:
'ip' IP networks and associated data referenced using either an IPv4 o 'ip' : IP networks and associated data referenced using either an
or IPv6 address. IPv4 or IPv6 address.
'autnum' Autonomous system registrations and associated data o 'autnum' : Autonomous system registrations and associated data
referenced using an AS Plain autonomous system number. referenced using an AS Plain autonomous system number.
'rdns' Reverse DNS information and associated data referenced using o 'rdns' : Reverse DNS information and associated data referenced
a fully-qualified domain name. using a fully-qualified domain name.
3.1. IP Networks 3.1. IP Networks
Queries for information about IP networks are of the form /ip/XXX/... 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 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 IPv4 [RFC0791] or IPv6 [RFC5952] address (i.e. XXX) or an IPv4 or
IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY). IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY).
Semantically, the simpler form using the address can be thought of as 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 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 IPv6. A given specific address or CIDR may fall within multiple IP
networks in a hierarchy of networks, therefore this query targets the networks in a hierarchy of networks, therefore this query targets the
"most-specific" or lowest IP network which completely encompasses it "most-specific" or lowest IP network which completely encompasses it
in a hierarchy of IP networks. in a hierarchy of IP networks.
Path segments following the IP address or CIDR notation target Path segments following the IP address or CIDR notation target
specific information associated with the targetted IP network in the specific information associated with the targetted IP network in the
following way: following way:
'registration' The query is for the network registration data. o 'registration' : The query is for the network registration data.
'operator' The query is for data about the network operator of the o 'operator' : The query is for data about the network operator of
IP network. The network operator is not always considered to be the IP network. The network operator is not always considered to
the end user or end site customer of the IP network, a distinction be the end user or end site customer of the IP network, a
made in some cases. For example, a residential Internet distinction made in some cases. For example, a residential
installation may be assigned IP addresses, but the provider from Internet installation may be assigned IP addresses, but the
whom they receive Internet access is considered the network provider from whom they receive Internet access is considered the
operator. Another rule of thumb is that the network operator is network operator. Another rule of thumb is that the network
the entity contacted to coordinate network issues and has operator is the entity contacted to coordinate network issues and
published contact information for this purpose, and operator has published contact information for this purpose, and operator
information can be further decomposed into operator contact information can be further decomposed into operator contact
information, which is returned with the 'operator' query when not information, which is returned with the 'operator' query when not
specifically targetted (see below). specifically targetted (see below).
When no path segment follows the IP address, the semantics of the When no path segment follows the IP address, the semantics of the
query are that both registration and operator information are to be query are that both registration and operator information are to be
returned. returned.
The following example URL [RFC3986] is a query for the IP network The following example URL [RFC3986] is a query for the IP network
registrion information. registrion information.
skipping to change at page 9, line 5 skipping to change at page 9, line 5
For example, to find information on the zone serving the network For example, to find information on the zone serving the network
192.0.2/24, the following path would be used: 192.0.2/24, the following path would be used:
/rdns/2.0.192.in-addr.arpa /rdns/2.0.192.in-addr.arpa
The rdns path segment may be follwed by a 'registration' or The rdns path segment may be follwed by a 'registration' or
'operator' path segment or no additional path segment, all of which 'operator' path segment or no additional path segment, all of which
follow the semantics in Section 3.1. follow the semantics in Section 3.1.
4. Query Paramaters 4. Normative References
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, [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791,
September 1981. September 1981.
[RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
Address Text Representation", RFC 5952, August 2010. Address Text Representation", RFC 5952, August 2010.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
skipping to change at page 11, line 5 skipping to change at page 9, line 31
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing
(CIDR): The Internet Address Assignment and Aggregation (CIDR): The Internet Address Assignment and Aggregation
Plan", BCP 122, RFC 4632, August 2006. Plan", BCP 122, RFC 4632, August 2006.
[RFC5396] Huston, G. and G. Michaelson, "Textual Representation of [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of
Autonomous System (AS) Numbers", RFC 5396, December 2008. 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 Authors' Addresses
Andrew Lee Newton Andrew Lee Newton
American Registry for Internet Numbers American Registry for Internet Numbers
3635 Concorde Parkway 3635 Concorde Parkway
Chantilly, VA 20151 Chantilly, VA 20151
US US
Email: andy@arin.net Email: andy@arin.net
URI: http://www.arin.net URI: http://www.arin.net
 End of changes. 15 change blocks. 
58 lines changed or deleted 38 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/