Network Working Group A. Newton Internet-Draft ARIN Intended status: Standards Track K. Ranjbar Expires: September 12, 2012 RIPE NCC A. Servin LACNIC B. Ellacott APNIC March 11, 2012 JSON Responses to RESTful URL Queries for RIRs draft-newton-et-al-weirds-rir-json-response-01 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 September 12, 2012. 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 September 12, 2012 [Page 1] Internet-Draft RIR RESTful JSON RESPONSES March 2012 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Signalling for JSON . . . . . . . . . . . . . . . . . . . . . 4 3. JSON Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 9 4.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 11 5. The Entity Object . . . . . . . . . . . . . . . . . . . . . . 14 6. Normative References . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 Newton, et al. Expires September 12, 2012 [Page 2] Internet-Draft RIR RESTful JSON RESPONSES March 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 September 12, 2012 [Page 3] Internet-Draft RIR RESTful JSON RESPONSES March 2012 2. Signalling for JSON To receive JSON [RFC4627] 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 [RFC2616], however the use of multiple MIME types in the Accept header is NOT RECOMMENDED. Newton, et al. Expires September 12, 2012 [Page 4] Internet-Draft RIR RESTful JSON RESPONSES March 2012 3. JSON Naming Clients processing JSON [RFC4627] 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 only consist of the alphabetic ASCII characters A through Z in both uppercase and lowercase, underscore characters, and SHOULD NOT begin with an underscore character or the characters "xml". This restriction is a union of the Ruby programming language identifier syntax and the XML element name syntax and has two purposes. First, client implementers using modern programming languages such as Ruby or Java may use libraries that automatically promote JSON values to first order object attributes or members (e.g. using the example above, the values may be referenced as network.handle or network.lunarNic_beforeOneSmallStep). Second, a clean mapping between JSON and XML is easy to accomplish using the JSON representation. 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. Newton, et al. Expires September 12, 2012 [Page 5] Internet-Draft RIR RESTful JSON RESPONSES March 2012 4. 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. "/") 4.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 September 12, 2012 [Page 6] Internet-Draft RIR RESTful JSON RESPONSES March 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 [RFC0791] or IPv6 [RFC5952] Newton, et al. Expires September 12, 2012 [Page 7] Internet-Draft RIR RESTful JSON RESPONSES March 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 country of the network which MAY be in ISO 3166 2 character code [ISO.3166.1988] format parendHandle -- 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 5). The "operator" member of Figure 1, which maybe queried for directly using the "/operator" path, is described below. Newton, et al. Expires September 12, 2012 [Page 8] Internet-Draft RIR RESTful JSON RESPONSES March 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 5. The "contacts" member is an object containing three arrays: "tech", "admin", and "abuse". Each of these arrays contains entities (Section 5). That is, the "tech" array contains entity objects, each representing a tech contact, etc... 4.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 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 [RFC4627] object. Newton, et al. Expires September 12, 2012 [Page 9] Internet-Draft RIR RESTful JSON RESPONSES March 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 September 12, 2012 [Page 10] Internet-Draft RIR RESTful JSON RESPONSES March 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 country of the autnum which MAY be in ISO 3166 2 character code [ISO.3166.1988] 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 5). 4.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 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 [RFC4627] object. Newton, et al. Expires September 12, 2012 [Page 11] Internet-Draft RIR RESTful JSON RESPONSES March 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 September 12, 2012 [Page 12] Internet-Draft RIR RESTful JSON RESPONSES March 2012 name -- a string denoting the DNS zone name, see [RFC4343] nameservers -- an array of strings, each being a fully qualified DNS name [RFC4343] 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 5). Newton, et al. Expires September 12, 2012 [Page 13] Internet-Draft RIR RESTful JSON RESPONSES March 2012 5. 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 September 12, 2012 [Page 14] Internet-Draft RIR RESTful JSON RESPONSES March 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 [RFC5322] 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, which SHOULD be in RFC 3339 [RFC3339] format lastChangedDate -- a string containing the date of last change made to the entity, which SHOULD be in RFC 3339 format lastChangedBy -- a string containing an identifier of the party responsible for the last change made to the entity registration Newton, et al. Expires September 12, 2012 [Page 15] Internet-Draft RIR RESTful JSON RESPONSES March 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. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, "Resource Records for the DNS Security Extensions", RFC 4034, March 2005. [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, August 2010. [ISO.3166.1988] International Organization for Standardization, "Codes for the representation of names of countries, 3rd edition", ISO Standard 3166, August 1988. [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of Autonomous System (AS) Numbers", RFC 5396, December 2008. [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity Clarification", RFC 4343, January 2006. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, October 2008. [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. Newton, et al. Expires September 12, 2012 [Page 16] Internet-Draft RIR RESTful JSON RESPONSES March 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 September 12, 2012 [Page 17]