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 12, 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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

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.

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".

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:

• operator information (e.g. "/operator")
• contacts of the operator (e.g "/operator/contacts")
• specific types of contacts of the operator (e.g. "/operator/contacts/abuse")
• registration information about the networks, AS numbers, or DNS delegations (e.g. "/registration")
• 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.

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: entity object [entity_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

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

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": [
      ...
    ]
  }
}

                    

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 [entity_object]. 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.

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: entity object [entity_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

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

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.

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: entity object [entity_object].

handle

-- a string representing an RIR unique identifier of the reverse DNS delegation

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

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"
    }        
                    
                

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

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

6. References

Authors' Addresses

Table of Contents

• 1. Introduction
• 2. Congruence With Other Registry Data Access Protocols
• 3. Responses
• 3.1. IP Networks
• 3.2. Autonomous Systems
• 3.3. Reverse DNS
• 4. The Entity Object
• 5. IANA Considerations
• 6. References
• Authors' Addresses