Network Working Group A. Newton Internet-Draft ARIN Intended status: Standards Track K. Ranjbar Expires: September 12, 2012 RIPE NCC A. Servin LACNIC B. Ellacott APNIC March 11, 2012 A Uniform RESTful URL Query Pattern for RIRs draft-newton-et-al-weirds-rir-query-01 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. 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 September 12, 2012 [Page 1] Internet-Draft Uniform RESTful RIR URLs March 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. Design Intents . . . . . . . . . . . . . . . . . . . . . . . . 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 Newton, et al. Expires September 12, 2012 [Page 2] Internet-Draft Uniform RESTful RIR URLs March 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 September 12, 2012 [Page 3] Internet-Draft Uniform RESTful RIR URLs March 2012 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. 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 described further in this document. Operators are able to make use of these mechanisms according to their local policy, including cache control, authorization, compression, and redirection. HTTP also benefits from widespread investment in scalability, reliability, and performance Newton, et al. Expires September 12, 2012 [Page 4] Internet-Draft Uniform RESTful RIR URLs March 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: 'ip' IP networks and associated data referenced using either an IPv4 or IPv6 address. 'autnum' Autonomous system registrations and associated data referenced using an AS Plain autonomous system number. '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: 'registration' The query is for the network registration data. '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 September 12, 2012 [Page 5] Internet-Draft Uniform RESTful RIR URLs March 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 September 12, 2012 [Page 6] Internet-Draft Uniform RESTful RIR URLs March 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 September 12, 2012 [Page 7] Internet-Draft Uniform RESTful RIR URLs March 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 September 12, 2012 [Page 8] Internet-Draft Uniform RESTful RIR URLs March 2012 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. Newton, et al. Expires September 12, 2012 [Page 9] Internet-Draft Uniform RESTful RIR URLs March 2012 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. Newton, et al. Expires September 12, 2012 [Page 10] Internet-Draft Uniform RESTful RIR URLs March 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 September 12, 2012 [Page 11]