Internet DRAFT - draft-newton-et-al-weirds-rir-json-response
draft-newton-et-al-weirds-rir-json-response
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
JSON Responses to RESTful URL Queries for RIRs
draft-newton-et-al-weirds-rir-json-response-02
Abstract
This document describes responses in the JSON format to the RESTful
queries described in draft-newton-et-al-weirds-rir-query.
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
include Simplified BSD License text as described in Section 4.e of
Newton, et al. Expires January 13, 2013 [Page 1]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
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. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 8
3.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 10
4. The Entity Object . . . . . . . . . . . . . . . . . . . . . . 13
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
6. Normative References . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
Newton, et al. Expires January 13, 2013 [Page 2]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
1. Introduction
The Regional Internet Registries (RIRs) have begun experimenting with
RESTful web services for access to Whois data. RIR-QUERY
[I-D.newton-et-al-weirds-rir-query] presents uniform patterns which
may be used to contruct URLs for accessing data from these RESTful
web services. This document describes responses in the JSON
[RFC4627] serialization format to the query URLs in RIR-QUERY.
As this document describes responses returned in JSON [RFC4627]
format, other documents may describe responses in other formats to
the same URL queries.
Newton, et al. Expires January 13, 2013 [Page 3]
Internet-Draft RIR RESTful JSON RESPONSES 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).
Of specific note, the signalling for JSON, JSON naming scheme, and
normalized references to other specifications are documented in
[I-D.designteam-weirds-using-http].
With specific regards to JSON format signalling, this document
defines and registers the media type "application/nrrdap+json", and
conformance to this specification is level 0. The JSON value for to
be used within the rdapConformance array is "nrrdap_level_0".
Newton, et al. Expires January 13, 2013 [Page 4]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
3. Responses
As specified in RIR-QUERY [I-D.newton-et-al-weirds-rir-query],
queries for resources and information can be made for three types of
information: 1) information about IP networks, 2) information about
autonomous system numbers, and 3) information about reverse DNS
delegations. Queries for each of these three types can be
constructed to target specific information:
o operator information (e.g. "/operator")
o contacts of the operator (e.g "/operator/contacts")
o specific types of contacts of the operator (e.g. "/operator/
contacts/abuse")
o registration information about the networks, AS numbers, or DNS
delegations (e.g. "/registration")
o all of the above (e.g. "/")
Unless otherwise stated, data types of the values listed in this
section are referenced in [I-D.designteam-weirds-using-http].
3.1. IP Networks
The following is an elided example of a JSON [RFC4627] response
object to a query for both registration and operator information of
an IP network
{
"network":
{
...
},
"operator":
{
...
}
}
Figure 1
The "network" member, which may be queried for directly as the
registration information (i.e. "/registration") of the IP network is
described below.
Newton, et al. Expires January 13, 2013 [Page 5]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
The following is an example of the JSON object for the network
registration information
{
"handle" : "XXXX-RIR",
"startAddress" : "10.0.0.0",
"endAddress" : "10.0.0.255",
"ipVersion" : 4,
"name": "NET-RTR-1",
"description" : [ "A network used for routing" ],
"type" : "DIRECT ALLOCATION",
"country" : "AU",
"parentHandle" : "YYYY-RIR",
"remarks" : [
"she sells seas shells",
"down by the seashore"
],
"uris" : [
{
"type" : "source",
"uri" : "http://whois-rws.net/network/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/network/yyyy"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com"
}
The following is a description of the members of this object:
handle -- a string representing an RIR unique identifier of the
network registration
startAddress -- the starting IP address of the network, either IPv4
or IPv6
Newton, et al. Expires January 13, 2013 [Page 6]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
endAddress -- the ending IP address of the network, either IPv4 or
IPv6
ipVersion -- an integer signifying the IP protocol version of the
network: 4 signifying an IPv4 network, 6 signifing an IPv6 network
name -- an identifier assigned to the network registration by the
registration holder
description -- an array of strings containing descriptive text about
the network registration
type -- a string containing an RIR specific classification of the
network
country -- a string containing the name of the 2 character country
code of the network
parentHandle -- a string containing an RIR unique identifier of the
parent network of this network registration
The members "remarks", "uris", "registrationDate", "lastChangedDate",
and "lastChangedBy" take the same form of the members of the same
name of the entity object (Section 4).
The "operator" member of Figure 1, which maybe queried for directly
using the "/operator" path, is described below.
Newton, et al. Expires January 13, 2013 [Page 7]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
The following is an elided example of a JSON response object for
operator information
{
"entity":
{
...
},
"contacts":
{
"tech": [
...
],
"admin": [
...
],
"abuse": [
...
]
}
}
Figure 2
The "entity" member of Figure 2 is an object and is specified in
Section 4. The "contacts" member is an object containing three
arrays: "tech", "admin", and "abuse". Each of these arrays contains
entities (Section 4). That is, the "tech" array contains entity
objects, each representing a tech contact, etc...
3.2. Autonomous Systems
An autonomous number query for both the registration and operator
and/or contact information yields an object containing an "autnum"
member and an "operator" member. The "operator" member is as
specified in Section 3.1. Additionally, queries specifically for the
operator and/or contact information take the same form as in
Section 3.1.
The "autnum" member mentioned above as well as queries directly for
the registration information take the form of a JSON [RFC4627]
object.
Newton, et al. Expires January 13, 2013 [Page 8]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
The following is an example of a JSON object representing an autnum.
{
"handle" : "XXXX-RIR",
"startAutnum" : "10",
"endAutnum" : "15",
"name": "AS-RTR-1",
"description" : [ "AS for Exchange" ],
"type" : "DIRECT ALLOCATION",
"country": "AU",
"remarks" : [
"she sells seas shells",
"down by the seashore"
],
"uris" : [
{
"type" : "source",
"uri" : "http://whois-rws.net/autnum/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/autnum/yyyy"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com"
}
The following is a description of the members of this object:
handle -- a string representing an RIR unique identifier of the
autnum registration
startAutnum -- the starting number [RFC5396] in the block of
autonomous system numbers
endAutnum -- the ending number [RFC5396] in the block of autonomous
system numbers
Newton, et al. Expires January 13, 2013 [Page 9]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
name an identifier assigned to the autnum registration by the
registration holder
description -- an array of strings containing descriptive text about
the autnum registration
type -- a string containing an RIR specific classification of the
autnum
country -- a string containing the name of the 2 character country
code of the autnum
The members "remarks", "uris", "registrationDate", "lastChangedDate",
and "lastChangedBy" take the same form of the members of the same
name of the entity object (Section 4).
3.3. Reverse DNS
A reverse DNS delegation query for both the registration and operator
and/or contact information yields an object containing an "rdns"
member and an "operator" member. The "operator" member is as
specified in Section 3.1. Additionally, queries specifically for the
operator and/or contact information take the same form as in
Section 3.1.
The "rdns" member mentioned above as well as queries directly for the
reverse DNS information take the form of a JSON [RFC4627] object.
Newton, et al. Expires January 13, 2013 [Page 10]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
The following is an example of a JSON object representing an reverse
DNS delegation.
{
"handle" : "XXXX-RIR",
"name" : "192.in-addr.arpa",
"nameServers" : [ "ns1.rir.net", "ns2.rir.net" ],
"delegationKeys" : [
{
"algorithm": 7,
"digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C",
"digestType" : 1,
"keyTag" : 53814
}
],
"remarks" : [
"she sells seas shells",
"down by the seashore"
],
"uris" : [
{
"type" : "source",
"uri" : "http://whois-rws.net/network/xxxx"
},
{
"type" : "parent",
"uri" : "http://whois-rws.net/network/yyyy"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com"
}
The following is a description of the members of this object:
handle -- a string representing an RIR unique identifier of the
reverse DNS delegation
Newton, et al. Expires January 13, 2013 [Page 11]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
name -- a string denoting the DNS zone name, which is a domain name
nameservers -- an array of strings, each being a fully qualified DNS
name of a namesever
delegationKeys -- an array of objects, each with the following
members:
algorithm -- an integer as specified by the algorithm field of a
DNS DS record as specified by RFC 4034 [RFC4034] in
presentation format
digest -- an string as specified by the digest field of a DNS DS
record as specified by RFC 4034 in presentation format
digestType -- an integer as specified by the digest type field of
a DNS DS record as specified by RFC 4034 in presetnation format
keyTag -- an integer as specified by the key tag field of a DNS
DS record as specified by RFC 4034 in presentation format
The members "remarks", "uris", "registrationDate", "lastChangedDate",
and "lastChangedBy" take the same form of the members of the same
name of the entity object (Section 4).
Newton, et al. Expires January 13, 2013 [Page 12]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
4. The Entity Object
Throughout this document there is a need to represent the identity
and contact information of organizations, corporations, governments,
non-profits, clubs, individual persons, and informal groups of
people. All of these representations are so similar that it is best
to represent them in JSON [RFC4627] with one construct, the entity
object, to aid in the re-use of code by implementers.
The following is an example of an entity:
{
"handle" : "XXXX-RIR",
"names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ],
"postalAddress" : [
"123 Maple Ave",
"Suite 90001",
"Vancouver",
"BC",
"12393"
],
"emails" : [ "joe@bob.com", "bob@joe.com" ],
"phones" : {
"office" : [ "999-999-999-99", "111-111-111-11" ],
"fax" : [ "222-222-222-22" ],
"mobile" : [ "333-333-333-33" ]
},
"remarks" : [
"she sells seas shells",
"down by the seashore"
],
"uris" : [
{
"type" : "source",
"uri" : "http://whois-rws.net/contact/xxxx"
},
{
"type" : "held",
"uri" : "http://example.net/location/xxxx"
}
],
"registrationDate" : "20110509",
"lastChangedDate" : "20110509",
"lastChangedBy" : "joe@bob.com"
}
Newton, et al. Expires January 13, 2013 [Page 13]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
This object as the following members.
handle -- a string representing an RIR unique identifier of the
entity
names -- an array of strings, each signifying the name of the entity
postalAddress -- an array of string, each representing a line in a
postal address.
emails -- an array of strings, each containing an email address for
the entity
phones -- an object containg telephone information associated with
the entity, with the following members:
office -- an array of strings, each being a telephone number
fax -- an array of strings, each being a telephone number
mobile -- an array of strings, each being a telephone number
remarks -- an array of strings, each containing comments about the
entity
uris -- an array of objects, each object having the following
members:
type -- a string denoting the application type of the "uri" value
uri -- a string containing a URI [RFC3986]
registrationDate -- a string containing the date the entity was
registered
lastChangedDate -- a string containing the date of last change made
to the entity
lastChangedBy -- a string containing an identifier of the party
responsible for the last change made to the entity registration
Newton, et al. Expires January 13, 2013 [Page 14]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
5. IANA Considerations
This specification registers the "application/nrrdap+json" media
type.
Type name: application
Subtype name: nrrdap+json
Required parameters: n/a
Optional parameters: level
Encoding considerations: n/a
Security considerations: n/a
Interoperability considerations: n/a
Published specification: [[ this document ]]
Applications that use this media type: RESTful Whois applications
Additional information: n/a
Person & email address to contact for further information: Andy
Newton &andy@hxr.us&
Intended usage: COMMON
Restrictions on usage: none
Author: Andy Newton
Change controller: IETF
Newton, et al. Expires January 13, 2013 [Page 15]
Internet-Draft RIR RESTful JSON RESPONSES July 2012
6. Normative References
[I-D.newton-et-al-weirds-rir-query]
Newton, A., Ranjbar, K., and A. Servin, "A Uniform RESTful
URL Query Pattern for RIRs",
draft-newton-et-al-weirds-rir-query-00 (work in progress),
September 2011.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S.
Rose, "Resource Records for the DNS Security Extensions",
RFC 4034, March 2005.
[RFC5396] Huston, G. and G. Michaelson, "Textual Representation of
Autonomous System (AS) Numbers", RFC 5396, December 2008.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[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.
[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 16]
Internet-Draft RIR RESTful JSON RESPONSES 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 17]
