Internet DRAFT - draft-newton-et-al-weirds-rir-query
draft-newton-et-al-weirds-rir-query
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
A Uniform RESTful URL Query Pattern for RIRs
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 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
Newton, et al. Expires January 13, 2013 [Page 1]
Internet-Draft Uniform RESTful RIR URLs July 2012
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. 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. Normative References . . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Newton, et al. Expires January 13, 2013 [Page 2]
Internet-Draft Uniform RESTful RIR URLs July 2012
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.
Newton, et al. Expires January 13, 2013 [Page 3]
Internet-Draft Uniform RESTful RIR URLs 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).
Newton, et al. Expires January 13, 2013 [Page 4]
Internet-Draft Uniform RESTful RIR URLs July 2012
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
Newton, et al. Expires January 13, 2013 [Page 5]
Internet-Draft Uniform RESTful RIR URLs July 2012
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:
Newton, et al. Expires January 13, 2013 [Page 6]
Internet-Draft Uniform RESTful RIR URLs July 2012
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).
Newton, et al. Expires January 13, 2013 [Page 7]
Internet-Draft Uniform RESTful RIR URLs July 2012
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.
Newton, et al. Expires January 13, 2013 [Page 8]
Internet-Draft Uniform RESTful RIR URLs July 2012
4. 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.
Newton, et al. Expires January 13, 2013 [Page 9]
Internet-Draft Uniform RESTful RIR URLs 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 10]
