| Network Working Group | A.L. Newton |
| Internet-Draft | ARIN |
| Intended status: Standards Track | K. Ranjbar |
| Expires: August 01, 2012 | RIPE NCC |
| A.L. Servin | |
| LACNIC | |
| January 31, 2012 |
JSON Responses to RESTful URL Queries for RIRs
draft-newton-et-al-weirds-rir-json-response-00
This document describes responses in the JSON format to the RESTful queries described in draft-newton-et-al-weirds-rir-query.
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 August 01, 2012.
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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The Regional Internet Registries (RIRs) have begun experimenting with RESTful web services for access to Whois data. draft-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 serialization format to the query URLs in draft-newton-et-al-weirds-rir-query.
As this document describes responses returned in JSON format, other documents may describe responses in other formats to the same URL queries.
To receive JSON responses, clients SHOULD put the "application/json" MIME type in the Accept header. Servers SHOULD respond with JSON responses when this MIME type is present in the Accept header in accordance with the preference rules for the Accept header in HTTP, however the use of multiple MIME types in the Accept header is NOT RECOMMENDED.
Clients processing JSON responses SHOULD ignore values associated with unrecognized names. Servers MAY insert values signified by names into the JSON responses which are not specified in this document. Insertion of unspecified values into JSON responses SHOULD have names prefixed with a short identifier followed by an underscore followed by a meaningful name.
For example, "handle" is specified in this document as the name of a value which is a string containing an RIR unique identifier for a registration. The RIR of the Moon might desire to insert a value specific to their services denoting that a registration occured before or after the first moon landing. The name for such a value might take the form "lunarNic_beforeOneSmallStep".
JSON names SHOULD NOT contain punctuation, whitespace, or other characters typically not allowed in variable names of modern programming languages. This better enables clients to automatically promote JSON values to first order object attributes or members using the given JSON names. Using the examples above, a Java or Ruby programmer working with such a framework may be able to reference the values as network.handle or network.lunarNic_beforeOneSmallStep.
Clients processing JSON responses MUST be prepared for values specified in this document to be absent from a response as no JSON value listed in this document is required to appear in the response. In other words, servers MAY remove values as is needed by the policies of the server operator.
As specified in draft-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:
The following is an elided example of a JSON response object to a query for both registration and operator information of an IP network
{
"network":
{
...
},
"operator":
{
...
}
}
The "network" member, which may be queried for directly as the registration information (i.e. "/registration") of the IP network is described below.
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",
"parentId" : "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: entity object [entity_object].
The members "remarks", "uris", "registrationDate", "lastChangedDate", and "lastChangedBy" take the same form of the members of the same name of the
The "operator" member of Figure 1, which maybe queried for directly using the "/operator" path, is described below.
The following is an elided example of a JSON response object for operator information
{
"entity":
{
...
},
"contacts":
{
"tech": [
...
],
"admin": [
...
],
"abuse": [
...
]
}
}
The "entity" member of Figure 3 is an object and is specified in Section 5. The "contacts" member is an object containing three arrays: "tech", "admin", and "abuse". Each of these arrays contains entities [entity_object]. That is, the "tech" array contains entity objects, each representing a tech contact, etc...
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 4.1. Additionally, queries specifically for the operator and/or contact information take the same form as in Section 4.1.
The "autnum" member mentioned above as well as queries directly for the registration information take the form of a JSON object.
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",
"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: entity object [entity_object].
The members "remarks", "uris", "registrationDate", "lastChangedDate", and "lastChangedBy" take the same form of the members of the same name of the
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 4.1. Additionally, queries specifically for the operator and/or contact information take the same form as in Section 4.1.
The "rdns" member mentioned above as well as queries directly for the reverse DNS information take the form of a JSON object.
The following is an example of a JSON object representing an autnum.
{
"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: entity object [entity_object].
The members "remarks", "uris", "registrationDate", "lastChangedDate", and "lastChangedBy" take the same form of the members of the same name of the
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 with one construct, the entity object. Such re-use is beleived 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"
}
This object as the following members.