idnits 2.17.1 draft-newton-et-al-weirds-rir-json-response-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' Security considerations: n/a' ) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 303 has weird spacing: '... name an id...' -- The document date (July 12, 2012) is 4296 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2616' is defined on line 544, but no explicit reference was found in the text == Outdated reference: A later version (-02) exists of draft-newton-et-al-weirds-rir-query-00 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track K. Ranjbar 5 Expires: January 13, 2013 RIPE NCC 6 A. Servin 7 LACNIC 8 B. Ellacott 9 APNIC 10 July 12, 2012 12 JSON Responses to RESTful URL Queries for RIRs 13 draft-newton-et-al-weirds-rir-json-response-02 15 Abstract 17 This document describes responses in the JSON format to the RESTful 18 queries described in draft-newton-et-al-weirds-rir-query. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 13, 2013. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Congruence With Other Registry Data Access Protocols . . . . . 4 56 3. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 8 59 3.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 10 60 4. The Entity Object . . . . . . . . . . . . . . . . . . . . . . 13 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 62 6. Normative References . . . . . . . . . . . . . . . . . . . . . 16 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 65 1. Introduction 67 The Regional Internet Registries (RIRs) have begun experimenting with 68 RESTful web services for access to Whois data. RIR-QUERY 69 [I-D.newton-et-al-weirds-rir-query] presents uniform patterns which 70 may be used to contruct URLs for accessing data from these RESTful 71 web services. This document describes responses in the JSON 72 [RFC4627] serialization format to the query URLs in RIR-QUERY. 74 As this document describes responses returned in JSON [RFC4627] 75 format, other documents may describe responses in other formats to 76 the same URL queries. 78 2. Congruence With Other Registry Data Access Protocols 80 This document describes the URL patterns for a Number Resource 81 Registry Data Access Protocol (NRRD-AP) and describes a Registry Data 82 Access Protocol (RD-AP) adhering to 83 [I-D.designteam-weirds-using-http], the intent being a specification 84 for number resource registries useful and in the style similar to 85 other registry access protocols, such as Domain Name Registry Access 86 Protocols (DNRP-AP). 88 Of specific note, the signalling for JSON, JSON naming scheme, and 89 normalized references to other specifications are documented in 90 [I-D.designteam-weirds-using-http]. 92 With specific regards to JSON format signalling, this document 93 defines and registers the media type "application/nrrdap+json", and 94 conformance to this specification is level 0. The JSON value for to 95 be used within the rdapConformance array is "nrrdap_level_0". 97 3. Responses 99 As specified in RIR-QUERY [I-D.newton-et-al-weirds-rir-query], 100 queries for resources and information can be made for three types of 101 information: 1) information about IP networks, 2) information about 102 autonomous system numbers, and 3) information about reverse DNS 103 delegations. Queries for each of these three types can be 104 constructed to target specific information: 106 o operator information (e.g. "/operator") 108 o contacts of the operator (e.g "/operator/contacts") 110 o specific types of contacts of the operator (e.g. "/operator/ 111 contacts/abuse") 113 o registration information about the networks, AS numbers, or DNS 114 delegations (e.g. "/registration") 116 o all of the above (e.g. "/") 118 Unless otherwise stated, data types of the values listed in this 119 section are referenced in [I-D.designteam-weirds-using-http]. 121 3.1. IP Networks 123 The following is an elided example of a JSON [RFC4627] response 124 object to a query for both registration and operator information of 125 an IP network 127 { 128 "network": 129 { 130 ... 131 }, 132 "operator": 133 { 134 ... 135 } 136 } 138 Figure 1 140 The "network" member, which may be queried for directly as the 141 registration information (i.e. "/registration") of the IP network is 142 described below. 144 The following is an example of the JSON object for the network 145 registration information 147 { 148 "handle" : "XXXX-RIR", 149 "startAddress" : "10.0.0.0", 150 "endAddress" : "10.0.0.255", 151 "ipVersion" : 4, 152 "name": "NET-RTR-1", 153 "description" : [ "A network used for routing" ], 154 "type" : "DIRECT ALLOCATION", 155 "country" : "AU", 156 "parentHandle" : "YYYY-RIR", 157 "remarks" : [ 158 "she sells seas shells", 159 "down by the seashore" 160 ], 161 "uris" : [ 162 { 163 "type" : "source", 164 "uri" : "http://whois-rws.net/network/xxxx" 165 }, 166 { 167 "type" : "parent", 168 "uri" : "http://whois-rws.net/network/yyyy" 169 }, 170 { 171 "type" : "held", 172 "uri" : "http://example.net/location/xxxx" 173 } 174 ], 175 "registrationDate" : "20110509", 176 "lastChangedDate" : "20110509", 177 "lastChangedBy" : "joe@bob.com" 178 } 180 The following is a description of the members of this object: 182 handle -- a string representing an RIR unique identifier of the 183 network registration 185 startAddress -- the starting IP address of the network, either IPv4 186 or IPv6 188 endAddress -- the ending IP address of the network, either IPv4 or 189 IPv6 191 ipVersion -- an integer signifying the IP protocol version of the 192 network: 4 signifying an IPv4 network, 6 signifing an IPv6 network 194 name -- an identifier assigned to the network registration by the 195 registration holder 197 description -- an array of strings containing descriptive text about 198 the network registration 200 type -- a string containing an RIR specific classification of the 201 network 203 country -- a string containing the name of the 2 character country 204 code of the network 206 parentHandle -- a string containing an RIR unique identifier of the 207 parent network of this network registration 209 The members "remarks", "uris", "registrationDate", "lastChangedDate", 210 and "lastChangedBy" take the same form of the members of the same 211 name of the entity object (Section 4). 213 The "operator" member of Figure 1, which maybe queried for directly 214 using the "/operator" path, is described below. 216 The following is an elided example of a JSON response object for 217 operator information 219 { 220 "entity": 221 { 222 ... 223 }, 224 "contacts": 225 { 226 "tech": [ 227 ... 228 ], 229 "admin": [ 230 ... 231 ], 232 "abuse": [ 233 ... 234 ] 235 } 236 } 238 Figure 2 240 The "entity" member of Figure 2 is an object and is specified in 241 Section 4. The "contacts" member is an object containing three 242 arrays: "tech", "admin", and "abuse". Each of these arrays contains 243 entities (Section 4). That is, the "tech" array contains entity 244 objects, each representing a tech contact, etc... 246 3.2. Autonomous Systems 248 An autonomous number query for both the registration and operator 249 and/or contact information yields an object containing an "autnum" 250 member and an "operator" member. The "operator" member is as 251 specified in Section 3.1. Additionally, queries specifically for the 252 operator and/or contact information take the same form as in 253 Section 3.1. 255 The "autnum" member mentioned above as well as queries directly for 256 the registration information take the form of a JSON [RFC4627] 257 object. 259 The following is an example of a JSON object representing an autnum. 261 { 262 "handle" : "XXXX-RIR", 263 "startAutnum" : "10", 264 "endAutnum" : "15", 265 "name": "AS-RTR-1", 266 "description" : [ "AS for Exchange" ], 267 "type" : "DIRECT ALLOCATION", 268 "country": "AU", 269 "remarks" : [ 270 "she sells seas shells", 271 "down by the seashore" 272 ], 273 "uris" : [ 274 { 275 "type" : "source", 276 "uri" : "http://whois-rws.net/autnum/xxxx" 277 }, 278 { 279 "type" : "parent", 280 "uri" : "http://whois-rws.net/autnum/yyyy" 281 }, 282 { 283 "type" : "held", 284 "uri" : "http://example.net/location/xxxx" 285 } 286 ], 287 "registrationDate" : "20110509", 288 "lastChangedDate" : "20110509", 289 "lastChangedBy" : "joe@bob.com" 290 } 292 The following is a description of the members of this object: 294 handle -- a string representing an RIR unique identifier of the 295 autnum registration 297 startAutnum -- the starting number [RFC5396] in the block of 298 autonomous system numbers 300 endAutnum -- the ending number [RFC5396] in the block of autonomous 301 system numbers 303 name an identifier assigned to the autnum registration by the 304 registration holder 306 description -- an array of strings containing descriptive text about 307 the autnum registration 309 type -- a string containing an RIR specific classification of the 310 autnum 312 country -- a string containing the name of the 2 character country 313 code of the autnum 315 The members "remarks", "uris", "registrationDate", "lastChangedDate", 316 and "lastChangedBy" take the same form of the members of the same 317 name of the entity object (Section 4). 319 3.3. Reverse DNS 321 A reverse DNS delegation query for both the registration and operator 322 and/or contact information yields an object containing an "rdns" 323 member and an "operator" member. The "operator" member is as 324 specified in Section 3.1. Additionally, queries specifically for the 325 operator and/or contact information take the same form as in 326 Section 3.1. 328 The "rdns" member mentioned above as well as queries directly for the 329 reverse DNS information take the form of a JSON [RFC4627] object. 331 The following is an example of a JSON object representing an reverse 332 DNS delegation. 334 { 335 "handle" : "XXXX-RIR", 336 "name" : "192.in-addr.arpa", 337 "nameServers" : [ "ns1.rir.net", "ns2.rir.net" ], 338 "delegationKeys" : [ 339 { 340 "algorithm": 7, 341 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 342 "digestType" : 1, 343 "keyTag" : 53814 344 } 345 ], 346 "remarks" : [ 347 "she sells seas shells", 348 "down by the seashore" 349 ], 350 "uris" : [ 351 { 352 "type" : "source", 353 "uri" : "http://whois-rws.net/network/xxxx" 354 }, 355 { 356 "type" : "parent", 357 "uri" : "http://whois-rws.net/network/yyyy" 358 }, 359 { 360 "type" : "held", 361 "uri" : "http://example.net/location/xxxx" 362 } 363 ], 364 "registrationDate" : "20110509", 365 "lastChangedDate" : "20110509", 366 "lastChangedBy" : "joe@bob.com" 367 } 369 The following is a description of the members of this object: 371 handle -- a string representing an RIR unique identifier of the 372 reverse DNS delegation 374 name -- a string denoting the DNS zone name, which is a domain name 376 nameservers -- an array of strings, each being a fully qualified DNS 377 name of a namesever 379 delegationKeys -- an array of objects, each with the following 380 members: 382 algorithm -- an integer as specified by the algorithm field of a 383 DNS DS record as specified by RFC 4034 [RFC4034] in 384 presentation format 386 digest -- an string as specified by the digest field of a DNS DS 387 record as specified by RFC 4034 in presentation format 389 digestType -- an integer as specified by the digest type field of 390 a DNS DS record as specified by RFC 4034 in presetnation format 392 keyTag -- an integer as specified by the key tag field of a DNS 393 DS record as specified by RFC 4034 in presentation format 395 The members "remarks", "uris", "registrationDate", "lastChangedDate", 396 and "lastChangedBy" take the same form of the members of the same 397 name of the entity object (Section 4). 399 4. The Entity Object 401 Throughout this document there is a need to represent the identity 402 and contact information of organizations, corporations, governments, 403 non-profits, clubs, individual persons, and informal groups of 404 people. All of these representations are so similar that it is best 405 to represent them in JSON [RFC4627] with one construct, the entity 406 object, to aid in the re-use of code by implementers. 408 The following is an example of an entity: 410 { 411 "handle" : "XXXX-RIR", 412 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 413 "postalAddress" : [ 414 "123 Maple Ave", 415 "Suite 90001", 416 "Vancouver", 417 "BC", 418 "12393" 419 ], 420 "emails" : [ "joe@bob.com", "bob@joe.com" ], 421 "phones" : { 422 "office" : [ "999-999-999-99", "111-111-111-11" ], 423 "fax" : [ "222-222-222-22" ], 424 "mobile" : [ "333-333-333-33" ] 425 }, 426 "remarks" : [ 427 "she sells seas shells", 428 "down by the seashore" 429 ], 430 "uris" : [ 431 { 432 "type" : "source", 433 "uri" : "http://whois-rws.net/contact/xxxx" 434 }, 435 { 436 "type" : "held", 437 "uri" : "http://example.net/location/xxxx" 438 } 439 ], 440 "registrationDate" : "20110509", 441 "lastChangedDate" : "20110509", 442 "lastChangedBy" : "joe@bob.com" 443 } 445 This object as the following members. 447 handle -- a string representing an RIR unique identifier of the 448 entity 450 names -- an array of strings, each signifying the name of the entity 452 postalAddress -- an array of string, each representing a line in a 453 postal address. 455 emails -- an array of strings, each containing an email address for 456 the entity 458 phones -- an object containg telephone information associated with 459 the entity, with the following members: 461 office -- an array of strings, each being a telephone number 463 fax -- an array of strings, each being a telephone number 465 mobile -- an array of strings, each being a telephone number 467 remarks -- an array of strings, each containing comments about the 468 entity 470 uris -- an array of objects, each object having the following 471 members: 473 type -- a string denoting the application type of the "uri" value 475 uri -- a string containing a URI [RFC3986] 477 registrationDate -- a string containing the date the entity was 478 registered 480 lastChangedDate -- a string containing the date of last change made 481 to the entity 483 lastChangedBy -- a string containing an identifier of the party 484 responsible for the last change made to the entity registration 486 5. IANA Considerations 488 This specification registers the "application/nrrdap+json" media 489 type. 491 Type name: application 493 Subtype name: nrrdap+json 495 Required parameters: n/a 497 Optional parameters: level 499 Encoding considerations: n/a 501 Security considerations: n/a 503 Interoperability considerations: n/a 505 Published specification: [[ this document ]] 507 Applications that use this media type: RESTful Whois applications 509 Additional information: n/a 511 Person & email address to contact for further information: Andy 512 Newton &andy@hxr.us& 514 Intended usage: COMMON 516 Restrictions on usage: none 518 Author: Andy Newton 520 Change controller: IETF 522 6. Normative References 524 [I-D.newton-et-al-weirds-rir-query] 525 Newton, A., Ranjbar, K., and A. Servin, "A Uniform RESTful 526 URL Query Pattern for RIRs", 527 draft-newton-et-al-weirds-rir-query-00 (work in progress), 528 September 2011. 530 [RFC4627] Crockford, D., "The application/json Media Type for 531 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 533 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 534 Rose, "Resource Records for the DNS Security Extensions", 535 RFC 4034, March 2005. 537 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 538 Autonomous System (AS) Numbers", RFC 5396, December 2008. 540 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 541 Resource Identifier (URI): Generic Syntax", STD 66, 542 RFC 3986, January 2005. 544 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 545 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 546 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 548 [I-D.designteam-weirds-using-http] 549 Newton, A., Ranjbar, K., Servin, A., Ellacott, B., 550 Hollenbeck, S., Sheng, S., Arias, F., Kong, N., and F. 551 Obispo, "Using HTTP for RESTful Whois Services by Internet 552 Registries", draft-designteam-weirds-using-http-01 (work 553 in progress), May 2012. 555 Authors' Addresses 557 Andrew Lee Newton 558 American Registry for Internet Numbers 559 3635 Concorde Parkway 560 Chantilly, VA 20151 561 US 563 Email: andy@arin.net 564 URI: http://www.arin.net 566 Kaveh Ranjbar 567 RIPE Network Coordination Centre 568 Singel 258 569 Amsterdam 1016AB 570 NL 572 Email: kranjbar@ripe.net 573 URI: http://www.ripe.net 575 Arturo L. Servin 576 Latin American and Caribbean Internet Address Registry 577 Rambla Republica de Mexico 6125 578 Montevideo 11300 579 UY 581 Email: aservin@lacnic.net 582 URI: http://www.lacnic.net 584 Byron J. Ellacott 585 Asia Pacific Network Information Center 586 6 Cordelia Street 587 South Brisbane QLD 4101 588 Australia 590 Email: bje@apnic.net 591 URI: http://www.apnic.net