idnits 2.17.1 draft-newton-et-al-weirds-rir-query-01.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? ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 268: '...f their choosing. Servers MUST ignore...' RFC 2119 keyword, line 277: '...l others, server SHOULD ignore unknown...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2012) is 4429 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: 4 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: September 12, 2012 RIPE NCC 6 A. Servin 7 LACNIC 8 B. Ellacott 9 APNIC 10 March 11, 2012 12 A Uniform RESTful URL Query Pattern for RIRs 13 draft-newton-et-al-weirds-rir-query-01 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 September 12, 2012. 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. Design Intents . . . . . . . . . . . . . . . . . . . . . . . . 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. Query Paramaters . . . . . . . . . . . . . . . . . . . . . . . 9 62 5. Normative References . . . . . . . . . . . . . . . . . . . . . 10 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 65 1. Introduction 67 The Regional Internet Registries (RIRs) have begun experimenting with 68 RESTful web services for access to Whois data. This document 69 presents uniform patterns which may be used to contruct URLs for 70 accessing data from these RESTful web services. 72 The patterns described in this document purposefully do not encompass 73 all of the methods employed in the Whois and RESTful web services of 74 all of the RIRs. The intent of the patterns described here are to 75 enable lookups of networks by IP address, autonomous system numbers 76 by number, and reverse DNS meta-data reverse DNS domain labels. It 77 is envisioned that each RIR will continue to maintain NICNAME/WHOIS 78 and/or RESTful web services specific to their needs and those of 79 their constituencies, and the information retreived through the 80 patterns described here may reference such services. 82 Whois services, in general, are read-only services. Therefore URL 83 [RFC3986] patterns presented here are only applicable to the HTTP 84 [RFC2616] GET and HEAD methods. 86 This document does not describe the results or entities returned from 87 issuing the described URLs with an HTTP GET. It is envisioned that 88 other documents will describe these entities in various serialization 89 formats, such as XML and JSON. 91 Additionally, resource management, provisioning and update functions 92 are out of scope for this document. RIRs have various and divergent 93 methods covering these functions, and it is unlikely a uniform 94 approach for these functions will ever be possible. 96 And while HTTP contains mechanisms for servers to authenticate 97 clients and clients to authenticate servers, from which authorization 98 schemes may be built, both authentication of clients and servers and 99 authorization for access to data are out-of-scope of this document. 100 In general, these matters require "policy" and are not the domain of 101 technical standards bodies. 103 2. Design Intents 105 There are a few design criteria this document attempts to support. 107 First, each query is meant to return either zero or one result. With 108 the maximum upper bound being set to one, the issuance of redirects 109 is simplified to the known document model used by HTTP [RFC2616]. 110 Should a result contain more than one result, some of which are 111 better served by other servers, the redirection model becomes much 112 more complicated. 114 Second, response formats are not specified in this document as the 115 intent is to leave room for multiple format types. 117 Third, HTTP offers a number of transport protocol mechanisms not 118 described further in this document. Operators are able to make use 119 of these mechanisms according to their local policy, including cache 120 control, authorization, compression, and redirection. HTTP also 121 benefits from widespread investment in scalability, reliability, and 122 performance 124 3. Path Specification 126 The uniform patterns start with a base URL [RFC3986] specified by 127 each RIR or any other service provider offering this service. The 128 base URL will be appended with resource type specific path segments. 129 The base URL may contain its own path segments (e.g. 130 http://example.com/... or http://example.com/restful-whois/... ). 132 The resource type path segments are: 134 'ip' IP networks and associated data referenced using either an IPv4 135 or IPv6 address. 137 'autnum' Autonomous system registrations and associated data 138 referenced using an AS Plain autonomous system number. 140 'rdns' Reverse DNS information and associated data referenced using 141 a fully-qualified domain name. 143 3.1. IP Networks 145 Queries for information about IP networks are of the form /ip/XXX/... 146 or /ip/XXX/YY/... where the path segment following 'ip' is either an 147 IPv4 [RFC0791] or IPv6 [RFC5952] address (i.e. XXX) or an IPv4 or 148 IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY). 149 Semantically, the simpler form using the address can be thought of as 150 a CIDR block with a length of 32 for IPv4 and a length of 128 for 151 IPv6. A given specific address or CIDR may fall within multiple IP 152 networks in a hierarchy of networks, therefore this query targets the 153 "most-specific" or lowest IP network which completely encompasses it 154 in a hierarchy of IP networks. 156 Path segments following the IP address or CIDR notation target 157 specific information associated with the targetted IP network in the 158 following way: 160 'registration' The query is for the network registration data. 162 'operator' The query is for data about the network operator of the 163 IP network. The network operator is not always considered to be 164 the end user or end site customer of the IP network, a distinction 165 made in some cases. For example, a residential Internet 166 installation may be assigned IP addresses, but the provider from 167 whom they receive Internet access is considered the network 168 operator. Another rule of thumb is that the network operator is 169 the entity contacted to coordinate network issues and has 170 published contact information for this purpose, and operator 171 information can be further decomposed into operator contact 172 information, which is returned with the 'operator' query when not 173 specifically targetted (see below). 175 When no path segment follows the IP address, the semantics of the 176 query are that both registration and operator information are to be 177 returned. 179 The following example URL [RFC3986] is a query for the IP network 180 registrion information. 182 http://example.com/somepath/ip/192.0.2.0/registration 184 The following example URL is a query for the IP network registration 185 information for the most specific IP network starting with 192.0.2.0 186 and ending with 192.0.2.255. 188 http://example.com/somepath/ip/192.0.2.0/24/registration 190 The following example URL is a query for the network operator 191 information of the most specific network containing 192.0.2.0 193 http://example.com/somepath/ip/192.0.2.0/operator 195 And this is an example URL for both the registration and operator 196 information of the most specific network containing 192.0.2.0 198 http://example.com/somepath/ip/192.0.2.0 200 This is an example of a URL for both the registration and operator 201 information of the most specific network containing 192.0.2.0/24. 203 http://example.com/somepath/ip/192.0.2.0/24 205 The contact information of an operator maybe specifically targetted 206 by following it with a 'contacts' path segment. And the type of 207 contact information may be further targetted by following that path 208 segment with a type. The types are: 210 o tech 212 o admin 214 o abuse 216 For example: 218 /ip/192.0.2.0/operator/contacts 220 returns all the contact information for the network operator of the 221 most specific network containing IP address 192.0.2.0. 223 And this path targets only the abuse contacts of that network 224 operator. 226 /ip/192.0.2.0/operator/contacts/abuse 228 3.2. Autonomous Systems 230 Queries for information regarding autonomous system number 231 registrations are of the form /autnum/XXX/... where XXX is an 232 autonomous system number [RFC5396]. In some registries, registration 233 of autonomous system numbers is done on an individual number basis, 234 while other registries may register blocks of autonomous system 235 numbers. The semantics of this query is such that if a number falls 236 within a range of registered blocks, the target of the query is the 237 block registration, and that individual number registrations are 238 considered a block of numbers with a size of 1. 240 For example, to find information on autonomous system number 65551, 241 the following path would be used: 243 /autnum/65551 245 The autnum path segment may be followed by a 'registration' or 246 'operator' path segment or no additional path segment, all of which 247 follow the semantics above (Section 3.1). 249 3.3. Reverse DNS 251 Queries for reverse DNS information are of the form 252 /rdns/XXXXXXXXX/... where XXXX is a fully-qualified domain name 253 [RFC4343] in either the in-addr.arpa or ip6.arpa zones. 255 For example, to find information on the zone serving the network 256 192.0.2/24, the following path would be used: 258 /rdns/2.0.192.in-addr.arpa 260 The rdns path segment may be follwed by a 'registration' or 261 'operator' path segment or no additional path segment, all of which 262 follow the semantics in Section 3.1. 264 4. Query Paramaters 266 To overcome issues with misbehaving HTTP [RFC2616] cache 267 infrastructure, clients may use the '__weirds__cachebust' query 268 parameter with a random value of their choosing. Servers MUST ignore 269 this query parameter. 271 The following is an example use of this parameter to retreive the 272 abuse contacts associated with the most specific IP network with the 273 address 192.0.2.0: 275 /ip/192.0.2.0/operator/contacts/abuse?__weirds_cachebust=xyz123 277 For all others, server SHOULD ignore unknown query parameters. 279 5. Normative References 281 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 282 September 1981. 284 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 285 Address Text Representation", RFC 5952, August 2010. 287 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 288 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 289 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 291 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 292 Clarification", RFC 4343, January 2006. 294 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 295 Resource Identifier (URI): Generic Syntax", STD 66, 296 RFC 3986, January 2005. 298 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 299 (CIDR): The Internet Address Assignment and Aggregation 300 Plan", BCP 122, RFC 4632, August 2006. 302 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 303 Autonomous System (AS) Numbers", RFC 5396, December 2008. 305 Authors' Addresses 307 Andrew Lee Newton 308 American Registry for Internet Numbers 309 3635 Concorde Parkway 310 Chantilly, VA 20151 311 US 313 Email: andy@arin.net 314 URI: http://www.arin.net 316 Kaveh Ranjbar 317 RIPE Network Coordination Centre 318 Singel 258 319 Amsterdam 1016AB 320 NL 322 Email: kranjbar@ripe.net 323 URI: http://www.ripe.net 325 Arturo L. Servin 326 Latin American and Caribbean Internet Address Registry 327 Rambla Republica de Mexico 6125 328 Montevideo 11300 329 UY 331 Email: aservin@lacnic.net 332 URI: http://www.lacnic.net 334 Byron J. Ellacott 335 Asia Pacific Network Information Center 336 6 Cordelia Street 337 South Brisbane QLD 4101 338 Australia 340 Email: bje@apnic.net 341 URI: http://www.apnic.net