One document matched: draft-newton-weirds-arin-whoisrws-00.txt
Network Working Group A. Newton
Internet-Draft American Registry for Internet
Intended status: Informational Numbers
Expires: December 5, 2011 June 3, 2011
ARIN's RESTful Web Service for Whois Data
draft-newton-weirds-arin-whoisrws-00
Abstract
This document describes the RESTful Web Service for Whois data as
implemented and fielded by the American Registry for Internet Numbers
(ARIN). ARIN calls this service Whois-RWS.
The purpose of this document is to facilitate discussion and serve as
input into a standards process in this area, currently being
discussed on the WHOIS-based Extensible Internet Registration Data
Service (WEIRDS) mailing list
(https://www.ietf.org/mailman/listinfo/weirds).
Please excuse this very rough initial draft. It is roughly based on
information currently published on ARIN's website. However, future
revisions of this document are planned, including discussions on
lessons learned by ARIN from the deployment of Whois-RWS and thoughts
on a future, unified standard.
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 December 5, 2011.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
Newton Expires December 5, 2011 [Page 1]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
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
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. Requirements notation . . . . . . . . . . . . . . . . . . . . 3
2. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Networks and Autonomous System Numbers . . . . . . . . . . 5
3.2. Delegations . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Organizations and Customers . . . . . . . . . . . . . . . 5
3.4. Points of Contact . . . . . . . . . . . . . . . . . . . . 6
3.5. General Query Behavior . . . . . . . . . . . . . . . . . . 6
4. Use of REST over HTTP . . . . . . . . . . . . . . . . . . . . 7
4.1. Data Formats and Versions . . . . . . . . . . . . . . . . 7
4.2. Schemas . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3. Resource Oriented URLs . . . . . . . . . . . . . . . . . . 8
4.3.1. Resources Related to Resources . . . . . . . . . . . . 9
4.3.2. Unrelated Lists of Resources . . . . . . . . . . . . . 10
4.3.3. IP Addresses . . . . . . . . . . . . . . . . . . . . . 11
4.3.4. Aggregate Resources . . . . . . . . . . . . . . . . . 11
4.3.5. Query Parameters . . . . . . . . . . . . . . . . . . . 12
5. HTTP Caching . . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Security Considerations . . . . . . . . . . . . . . . . . . . 14
7. Lessons Learned . . . . . . . . . . . . . . . . . . . . . . . 15
8. Normative References . . . . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17
Newton Expires December 5, 2011 [Page 2]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
1. Requirements notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in[RFC2119].
Newton Expires December 5, 2011 [Page 3]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
2. Background
ARIN offers public access to ARIN registration data via a number of
services. Traditionally, these services are known in the industry as
"Whois" in reference to the public data service of the ARPANET,
precursor of today's modern Internet. Whois services are offered by
all the Regional Internet Registries (RIRs), most Internet Routing
Registries (IRRs) and most domain name registries and registrars.
Traditionally, Whois services have been offered using the NICNAME/
WHOIS protocol as described by RFC 954 and RFC 3912. This protocol
is a simple, text based TCP protocol registered with in the Internet
Assigned Numbers Authority (IANA) for well-known port 43. RFC 3912,
the most recent specification for the protocol, does not define
either data types or data formats. As a consequence, Whois data
varies from service provider to service provider and is far from
ideal for programmatic consumption.
ARIN provides to the general public services for read-only access to
ARIN's registration data. These services include a user-friendly web
site (http://whois.arin.net), a RESTful Web Service, and a NICNAME/
WHOIS port 43 service. For the purposes of programmatic consumption,
ARIN recommends the use of the RESTful Web Service and strongly
discourages the use of the NICNAME/WHOIS port 43 service.
This document describes the RESTful Web Service for ARIN's Whois
data, which is known as Whois-RWS.
Newton Expires December 5, 2011 [Page 4]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
3. Data Model
ARIN's Whois-RWS data model is composed of six first order objects:
networks, autonomous system numbers, delegations, organizations,
points of contact, and customers. Each of these types, except
delegations, is directly addressable in a Whois service via a handle
(i.e. identifier). Within the Whois RESTful Web Service, these
handles are part of URLs that may be used to identify objects in
ARIN's Whois registration database by external, non-ARIN systems.
3.1. Networks and Autonomous System Numbers
Networks and Autonomous System Numbers (ASNs) are collectively
referred to as "resources" in ARIN parlance (this should not be
confused with the term "resources" in the context of RESTful Web
Services and Resource Oriented Architectures). They are the pieces
of information assigned or allocated to organizations for the
coordinated administration and operation of the Internet.
Networks signify the allocation or assignment of IP address space and
the contiguous IP CIDR blocks that make up that IP address space.
Handles for IPv4 networks start with "NET-", and handles for IPv6
networks start with "NET6-".
Autonomous System Numbers (ASNs) are used for the proper routing of
Internet packets. ARIN assigns ASNs in ranges, therefore a single
ASN is part of an ASN range allocation. The handles for these
registrations start with "AS" and are usually appended with the first
number of the ASN range.
3.2. Delegations
Delegations contain the information necessary for Reverse DNS,
including the associated nameservers, and DNS DS record information.
Unlike the other first order objects, delegations do not have a
Handle. Rather, they are directly addressable in a Whois service via
a delegation name (i.e. 0.192.in-addr.arpa.).
3.3. Organizations and Customers
Organizations are the registrants of resources and have a direct
relationship with ARIN. Organizations may be associated with many
resources. Customers do not have a direct relationship with ARIN
and, at present, may only be associated with one network
registration.
Customer handles start with "C", while organization handles have no
prefix.
Newton Expires December 5, 2011 [Page 5]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
3.4. Points of Contact
A Point of Contact (POC) is the registration of names, mailboxes,
and/or phone numbers which fulfill technical or administrative
functions on behalf of either an organization or a resource. POC
handles are usually appended with "-ARIN" though there are a few
exceptions.
3.5. General Query Behavior
For the first order objects addressable via handle, ARIN's Whois
services also allow for searching against names and other appropriate
fields contained within those objects. Unless otherwise specified,
these searches are case insensitive. Because ARIN's networks are
composed of multiple CIDR based network blocks, searches by IP
address or CIDR notation may sometimes yield what may, at first
blush, appear incorrect. For instance, a search for a particular
CIDR block may yield a network that covers the given CIDR block and
additional CIDR blocks composing the network, while a search by an IP
address will always yield the network or networks in which the IP
address falls.
Newton Expires December 5, 2011 [Page 6]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
4. Use of REST over HTTP
4.1. Data Formats and Versions
RESTful web services are not strictly tied to XML. ARIN's Whois
RESTful Web Service offers data in XML, JSON, plain text, and HTML
(actually, XHTML). However, ARIN's first order data format is XML as
there are many format and validation tools readily available for it,
and the other formats are offered on a best-effort basis.
If no desired format is specified, XML is the default format.
Specifying a desired data format may be accomplished in one of two
ways: either using the HTTP Accept header or using "file extensions".
A "file extension" appends a DOS like file extension to the path.
Though there only exists one version of this RESTful interface, it is
possible that the "data model" of the structured data such as XML and
JSON that is output by this service will need revision. Should it be
possible for ARIN to provide a backward compatible version, the HTTP
Accept header is the mechanism for specifying the desired version as
well as the data format.
The MIME type used in the Accept header will follow the format of
"application/arin.whoisrws-{version}+{format}". To use the latest
version of this service you would simply use the default MIME types
of "application/xml" or "application/json".
The following table lists the data types and their associated MIME
types and file extensions.
+------+----------------+-------------------------------+-----------+
| Data | Current | Version 1 MIME Type | File |
| Type | Version MIME | | Extension |
| | Type | | |
+------+----------------+-------------------------------+-----------+
| XML | application/xm | application/arin.whoisrws-v1+ | xml |
| | l | x ml | |
| | | | |
| JSON | application/js | application/arin.whoisrws-v1+ | json |
| | o n | j son | |
| | | | |
| plai | text/plain | | txt |
| n | | | |
| tex | | | |
| t | | | |
| | | | |
Newton Expires December 5, 2011 [Page 7]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
| HTML | text/html | | html |
+------+----------------+-------------------------------+-----------+
Table 1
4.2. Schemas
Relax NG stuff goes here.
Explanation of JSON and Badgerfish goes here.
4.3. Resource Oriented URLs
URLs point to resources. A typical URL might be
http://whois.arin.net/rest/poc/ALN-ARIN, which is a URL pointing to
the author of this document. Conceptually, this can be broken into a
base URL and the resource identifier:
base URL: http://whois.arin.net/rest
resource: /poc/ALN-ARIN
The base URL is just where ARIN is hosting the service. The real
interesting parts are the bits that identify the resources:
/poc this indicates the resource is a Point of Contact.
/ALN-ARIN this is the unique identifier for the Point of Contact, or
the POC Handle.
The Whois-RWS data model has six types of addressable resources.
These are reflected in Whois-RWS in the following way:
/poc point of contact
/org organization
/net a network
/asn autonomous system number(s)
/customer a customer of an organization
/rdns delegations in the reverse DNS
Newton Expires December 5, 2011 [Page 8]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
4.3.1. Resources Related to Resources
In the ARIN Whois data model, resources have relationships to other
resources. Getting references to these resources can be accomplished
by addressing the resource in question and applying a resource type
qualifier.
Here is the list of relationships (where "XXXX" signifies a handle):
/poc/XXXX
/orgs (i.e. /poc/XXXX/orgs) lists the organizations associated
with a given POC
/asns (i.e. /poc/XXXX/asns) lists the autonomous system numbers
associated with a given POC
/nets (i.e. /poc/XXXX/nets) lists the networks associated with a
given POC
/org/XXXX
/pocs (i.e. /org/XXXX/pocs) lists the points of contact
associated with a given organization
/asns (i.e. /org/XXXX/asns) lists the autonomous system numbers
associated with a given organization
/nets (i.e. /org/XXXX/nets) lists the networks associated with a
given organization
/asn/XXXX
/pocs (i.e. /asn/XXXX/pocs) lists the points of contact
associated with a given autonomous system number
/net/XXXX
/pocs (i.e. /net/XXXX/pocs) lists the points of contact
associated with a given network
/parent (i.e. /net/XXXX/parent) lists the parnet network of a
given network
/children (i.e. /net/XXXX/children) lists the child networks
associated with a given network
Newton Expires December 5, 2011 [Page 9]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
/rdns (i.e. /net/XXXX/rdns) lists the reverse DNS delegations
associated with a given network
/rdns/XXXX
/nets (i.e. /rdns/XXXX/nets) lists the networks associated with a
given reverse DNS delegation
4.3.2. Unrelated Lists of Resources
Unrelated lists of resources may be addressed using URL matrix
parameters. As an example, to find organizations with the name
"ARIN", the /orgs list is appended with the matrix parameter name to
form /orgs;name=ARIN (this is without the base URL).
Here is the list of resources and their supported matrix parameters:
/orgs
handle the handle of the organization
name the name of the organization
dba the "doing-business-as" name of the organization
/customers
handle the handle of the customer
name the name of the customer
/pocs
handle the handle of the POC
domain the domain name of an email address of the POC
first the first name of the POC
middle the middle name of the POC
last the last name of the POC
company the company name registered by the POC
Newton Expires December 5, 2011 [Page 10]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
city the city registered by the POC
/asns
handle the handle of the autonomous system number
name the name of the autonomous system number
/nets
handle the handle of the network
name the name of the network
4.3.3. IP Addresses
In the ARIN data model, an IP "network" is a set of associated IP
address blocks and the information related to these IP address blocks
and the set as a whole. A network can be composed of one IP address
block or of multiple IP address blocks. Networks are also
hierarchical, meaning that a network can have a parent and can have
children. An IP address or range of IP addresses can therefore fall
within the IP address block of multiple networks.
To get the networks that a particular IP address may fall within, one
can use the /ip/XX.XX.XX.XX resource, where XX.XX.XX.XX signifies the
IP address.
Networks may be looked up as well by supplying the full CIDR notation
of a range. To use the full CIDR notation, the resource looks like
/cidr/XX.XX.XX.XX/YY where XX.XX.XX.XX is the IP address prefix and
YY is the CIDR length.
Resources relative to the networks may be fetched using the /less and
/more path prefixes. /less will find the networks that are less
specific in scope (or wider), and /more will find the networks that
are more specific in scope (or narrower).
4.3.4. Aggregate Resources
Though Whois-RWS breaks down the ARIN data model into distinct
resources, end users have been accustomed to seeing many related
resources with one query over the NICNAME/WHOIS port 43 service.
While this can be accomplished by any Whois-RWS clients with multiple
queries, an aggregate resources can reduce the number of queries and
make this use case easier on client implementers.
For resources under /org, /net, /asn, and /ip, the URL may be
Newton Expires December 5, 2011 [Page 11]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
appended with "/pft" to produce an aggregate resource which includes
the resource being queried and related resources. If you can guess
what /pft means, I'll buy you a beer.
4.3.5. Query Parameters
4.3.5.1. Showing More of Detail
By default, lists of resources only show references to the resources.
However, lists can be expanded to show full detail by tacking on a
showDetails=true URL query parameter
(e.g.http://whois.arin.net/rest/org/ARIN/pocs?showDetails=true).
This query parameter also forces a resource to list its related
resources in line.
4.3.5.2. Showing Only Points of Contact
Some organizations have many, many associated resources. Having all
those resources returned when gathering information about an
organization maybe very undesirable. To allow getting all the POCs
of an organization without taking the penalty of retrieving all the
resources of the organization, the showPocs=true parameter may be
used. This parameter is only recognized when an organization's
information is referenced by handle.
4.3.5.3. Showing ARIN Resources
In the past, ARIN's NICNAME/WHOIS service yielded a "No Match" result
for searches of IP address space unallocated by ARIN but within
ARIN's IP address pool. This was somewhat confusing and could
possibly mislead a person into thinking the address space is simply
unallocated to any available address pool (in other words, still held
by the IANA). This has been changed in ARIN's NICNAME/WHOIS service
so it will return the appropriate ARIN network allocation for IP
addresses unallocated by ARIN. By default, the RESTful service will
also return the appropriate ARIN network allocation for IP addresses
unallocated by ARIN to ARIN constituents.
If the behavior is desired, the showARIN=false query parameter may be
used on IP and CIDR queries.
Newton Expires December 5, 2011 [Page 12]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
5. HTTP Caching
One of the advantages of a RESTful Web Service is that HTTP
infrastructure may be employed to make it more reliable and/or
robust. HTTP caching is one such tool to help with these goals.
ARIN employs caching at multiple levels and customized to address the
query pattern seen against ARIN's services.
If HTTP caching is be employed on the client side, there are a number
of issues to consider to craft a custom caching solution.
First caching should be restricted to URLs that have the highest
likelihood of remaining in the cache using the caches retention
strategy. In almost any scenario, caching RESTful resources under
/rest/ip will lead to a large dataset and a low cache hit ratio.
However, it is likely acceptable to cache resources under /rest/org,
/rest/poc, and /rest/net. It is recommended that cache statistics be
available for proper cache tuning.
Second, many HTTP caches base the cache objects on URLs. However,
the Accept header dictates the content of the object and may not be
part of the cache key of cached objects. Therefore it is possible to
get a cached object of one type when another type was requested. For
instance, /rest/poc/KOSTE-ARIN might return XML when JSON was
requested. To overcome this, it is advisable to use file extensions
to specify data format as file extensions are part of the URL.
Newton Expires December 5, 2011 [Page 13]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
6. Security Considerations
Of course there are some... but I'm not gonna tell you what they are.
Seriously.... to be discussed in future revisions.
Newton Expires December 5, 2011 [Page 14]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
7. Lessons Learned
to be discussed in a future revision, the lessons we have learned
from this
Newton Expires December 5, 2011 [Page 15]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
Newton Expires December 5, 2011 [Page 16]
Internet-Draft ARIN's RESTful Web Service for Whois Data June 2011
Author's Address
Andrew Lee Newton
American Registry for Internet Numbers
Newton Expires December 5, 2011 [Page 17]
| PAFTECH AB 2003-2024 | 2024-05-18 08:44:00 |