idnits 2.17.1 draft-newton-et-al-weirds-rir-query-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2012) is 4305 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track K. Ranjbar 5 Expires: January 13, 2013 RIPE NCC 6 A. Servin 7 LACNIC 8 B. Ellacott 9 APNIC 10 July 12, 2012 12 A Uniform RESTful URL Query Pattern for RIRs 13 draft-newton-et-al-weirds-rir-query-02 15 Abstract 17 This document describes uniform patterns for which to construct HTTP 18 URLs that may be used to retreive information from Regional Internet 19 Registries (RIRs) using "RESTful" web access patterns. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 13, 2013. 38 Copyright Notice 40 Copyright (c) 2012 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Congruence With Other Registry Data Access Protocols . . . . . 4 57 3. Path Specification . . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 7 60 3.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 8 61 4. Normative References . . . . . . . . . . . . . . . . . . . . . 9 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 64 1. Introduction 66 The Regional Internet Registries (RIRs) have begun experimenting with 67 RESTful web services for access to Whois data. This document 68 presents uniform patterns which may be used to contruct URLs for 69 accessing data from these RESTful web services. 71 The patterns described in this document purposefully do not encompass 72 all of the methods employed in the Whois and RESTful web services of 73 all of the RIRs. The intent of the patterns described here are to 74 enable lookups of networks by IP address, autonomous system numbers 75 by number, and reverse DNS meta-data reverse DNS domain labels. It 76 is envisioned that each RIR will continue to maintain NICNAME/WHOIS 77 and/or RESTful web services specific to their needs and those of 78 their constituencies, and the information retreived through the 79 patterns described here may reference such services. 81 Whois services, in general, are read-only services. Therefore URL 82 [RFC3986] patterns presented here are only applicable to the HTTP 83 [RFC2616] GET and HEAD methods. 85 This document does not describe the results or entities returned from 86 issuing the described URLs with an HTTP GET. It is envisioned that 87 other documents will describe these entities in various serialization 88 formats, such as XML and JSON. 90 Additionally, resource management, provisioning and update functions 91 are out of scope for this document. RIRs have various and divergent 92 methods covering these functions, and it is unlikely a uniform 93 approach for these functions will ever be possible. 95 And while HTTP contains mechanisms for servers to authenticate 96 clients and clients to authenticate servers, from which authorization 97 schemes may be built, both authentication of clients and servers and 98 authorization for access to data are out-of-scope of this document. 99 In general, these matters require "policy" and are not the domain of 100 technical standards bodies. 102 2. Congruence With Other Registry Data Access Protocols 104 This document describes the URL patterns for a Number Resource 105 Registry Data Access Protocol (NRRD-AP) and describes a Registry Data 106 Access Protocol (RD-AP) adhering to 107 [I-D.designteam-weirds-using-http], the intent being a specification 108 for number resource registries useful and in the style similar to 109 other registry access protocols, such as Domain Name Registry Access 110 Protocols (DNRP-AP). 112 3. Path Specification 114 The uniform patterns start with a base URL [RFC3986] specified by 115 each RIR or any other service provider offering this service. The 116 base URL will be appended with resource type specific path segments. 117 The base URL may contain its own path segments (e.g. 118 http://example.com/... or http://example.com/restful-whois/... ). 120 The resource type path segments are: 122 o 'ip' : IP networks and associated data referenced using either an 123 IPv4 or IPv6 address. 125 o 'autnum' : Autonomous system registrations and associated data 126 referenced using an AS Plain autonomous system number. 128 o 'rdns' : Reverse DNS information and associated data referenced 129 using a fully-qualified domain name. 131 3.1. IP Networks 133 Queries for information about IP networks are of the form /ip/XXX/... 134 or /ip/XXX/YY/... where the path segment following 'ip' is either an 135 IPv4 [RFC0791] or IPv6 [RFC5952] address (i.e. XXX) or an IPv4 or 136 IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY). 137 Semantically, the simpler form using the address can be thought of as 138 a CIDR block with a length of 32 for IPv4 and a length of 128 for 139 IPv6. A given specific address or CIDR may fall within multiple IP 140 networks in a hierarchy of networks, therefore this query targets the 141 "most-specific" or lowest IP network which completely encompasses it 142 in a hierarchy of IP networks. 144 Path segments following the IP address or CIDR notation target 145 specific information associated with the targetted IP network in the 146 following way: 148 o 'registration' : The query is for the network registration data. 150 o 'operator' : The query is for data about the network operator of 151 the IP network. The network operator is not always considered to 152 be the end user or end site customer of the IP network, a 153 distinction made in some cases. For example, a residential 154 Internet installation may be assigned IP addresses, but the 155 provider from whom they receive Internet access is considered the 156 network operator. Another rule of thumb is that the network 157 operator is the entity contacted to coordinate network issues and 158 has published contact information for this purpose, and operator 159 information can be further decomposed into operator contact 160 information, which is returned with the 'operator' query when not 161 specifically targetted (see below). 163 When no path segment follows the IP address, the semantics of the 164 query are that both registration and operator information are to be 165 returned. 167 The following example URL [RFC3986] is a query for the IP network 168 registrion information. 170 http://example.com/somepath/ip/192.0.2.0/registration 172 The following example URL is a query for the IP network registration 173 information for the most specific IP network starting with 192.0.2.0 174 and ending with 192.0.2.255. 176 http://example.com/somepath/ip/192.0.2.0/24/registration 178 The following example URL is a query for the network operator 179 information of the most specific network containing 192.0.2.0 181 http://example.com/somepath/ip/192.0.2.0/operator 183 And this is an example URL for both the registration and operator 184 information of the most specific network containing 192.0.2.0 186 http://example.com/somepath/ip/192.0.2.0 188 This is an example of a URL for both the registration and operator 189 information of the most specific network containing 192.0.2.0/24. 191 http://example.com/somepath/ip/192.0.2.0/24 193 The contact information of an operator maybe specifically targetted 194 by following it with a 'contacts' path segment. And the type of 195 contact information may be further targetted by following that path 196 segment with a type. The types are: 198 o tech 200 o admin 202 o abuse 204 For example: 206 /ip/192.0.2.0/operator/contacts 208 returns all the contact information for the network operator of the 209 most specific network containing IP address 192.0.2.0. 211 And this path targets only the abuse contacts of that network 212 operator. 214 /ip/192.0.2.0/operator/contacts/abuse 216 3.2. Autonomous Systems 218 Queries for information regarding autonomous system number 219 registrations are of the form /autnum/XXX/... where XXX is an 220 autonomous system number [RFC5396]. In some registries, registration 221 of autonomous system numbers is done on an individual number basis, 222 while other registries may register blocks of autonomous system 223 numbers. The semantics of this query is such that if a number falls 224 within a range of registered blocks, the target of the query is the 225 block registration, and that individual number registrations are 226 considered a block of numbers with a size of 1. 228 For example, to find information on autonomous system number 65551, 229 the following path would be used: 231 /autnum/65551 233 The autnum path segment may be followed by a 'registration' or 234 'operator' path segment or no additional path segment, all of which 235 follow the semantics above (Section 3.1). 237 3.3. Reverse DNS 239 Queries for reverse DNS information are of the form 240 /rdns/XXXXXXXXX/... where XXXX is a fully-qualified domain name 241 [RFC4343] in either the in-addr.arpa or ip6.arpa zones. 243 For example, to find information on the zone serving the network 244 192.0.2/24, the following path would be used: 246 /rdns/2.0.192.in-addr.arpa 248 The rdns path segment may be follwed by a 'registration' or 249 'operator' path segment or no additional path segment, all of which 250 follow the semantics in Section 3.1. 252 4. Normative References 254 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 255 September 1981. 257 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 258 Address Text Representation", RFC 5952, August 2010. 260 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 261 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 262 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 264 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 265 Clarification", RFC 4343, January 2006. 267 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 268 Resource Identifier (URI): Generic Syntax", STD 66, 269 RFC 3986, January 2005. 271 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 272 (CIDR): The Internet Address Assignment and Aggregation 273 Plan", BCP 122, RFC 4632, August 2006. 275 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 276 Autonomous System (AS) Numbers", RFC 5396, December 2008. 278 [I-D.designteam-weirds-using-http] 279 Newton, A., Ranjbar, K., Servin, A., Ellacott, B., 280 Hollenbeck, S., Sheng, S., Arias, F., Kong, N., and F. 281 Obispo, "Using HTTP for RESTful Whois Services by Internet 282 Registries", draft-designteam-weirds-using-http-01 (work 283 in progress), May 2012. 285 Authors' Addresses 287 Andrew Lee Newton 288 American Registry for Internet Numbers 289 3635 Concorde Parkway 290 Chantilly, VA 20151 291 US 293 Email: andy@arin.net 294 URI: http://www.arin.net 296 Kaveh Ranjbar 297 RIPE Network Coordination Centre 298 Singel 258 299 Amsterdam 1016AB 300 NL 302 Email: kranjbar@ripe.net 303 URI: http://www.ripe.net 305 Arturo L. Servin 306 Latin American and Caribbean Internet Address Registry 307 Rambla Republica de Mexico 6125 308 Montevideo 11300 309 UY 311 Email: aservin@lacnic.net 312 URI: http://www.lacnic.net 314 Byron J. Ellacott 315 Asia Pacific Network Information Center 316 6 Cordelia Street 317 South Brisbane QLD 4101 318 Australia 320 Email: bje@apnic.net 321 URI: http://www.apnic.net