idnits 2.17.1 draft-newton-et-al-weirds-rir-json-response-01.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. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 80: '... To receive JSON [RFC4627] responses, clients SHOULD put the...' RFC 2119 keyword, line 81: '... in the Accept header. Servers SHOULD...' RFC 2119 keyword, line 85: '... the Accept header is NOT RECOMMENDED....' RFC 2119 keyword, line 89: '... Clients processing JSON [RFC4627] responses SHOULD ignore values...' RFC 2119 keyword, line 90: '...ized names. Servers MAY insert values...' (9 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 326 has weird spacing: '... name an id...' -- The document date (March 11, 2012) is 4427 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) == 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: 5 errors (**), 0 flaws (~~), 3 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: September 12, 2012 RIPE NCC 6 A. Servin 7 LACNIC 8 B. Ellacott 9 APNIC 10 March 11, 2012 12 JSON Responses to RESTful URL Queries for RIRs 13 draft-newton-et-al-weirds-rir-json-response-01 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 September 12, 2012. 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. Signalling for JSON . . . . . . . . . . . . . . . . . . . . . 4 56 3. JSON Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 4.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 6 59 4.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 9 60 4.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 11 61 5. The Entity Object . . . . . . . . . . . . . . . . . . . . . . 14 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. Signalling for JSON 80 To receive JSON [RFC4627] responses, clients SHOULD put the 81 "application/json" MIME type in the Accept header. Servers SHOULD 82 respond with JSON responses when this MIME type is present in the 83 Accept header in accordance with the preference rules for the Accept 84 header in HTTP [RFC2616], however the use of multiple MIME types in 85 the Accept header is NOT RECOMMENDED. 87 3. JSON Naming 89 Clients processing JSON [RFC4627] responses SHOULD ignore values 90 associated with unrecognized names. Servers MAY insert values 91 signified by names into the JSON responses which are not specified in 92 this document. Insertion of unspecified values into JSON responses 93 SHOULD have names prefixed with a short identifier followed by an 94 underscore followed by a meaningful name. 96 For example, "handle" is specified in this document as the name of a 97 value which is a string containing an RIR unique identifier for a 98 registration. The RIR of the Moon might desire to insert a value 99 specific to their services denoting that a registration occured 100 before or after the first moon landing. The name for such a value 101 might take the form "lunarNic_beforeOneSmallStep". 103 JSON names SHOULD only consist of the alphabetic ASCII characters A 104 through Z in both uppercase and lowercase, underscore characters, and 105 SHOULD NOT begin with an underscore character or the characters 106 "xml". This restriction is a union of the Ruby programming language 107 identifier syntax and the XML element name syntax and has two 108 purposes. First, client implementers using modern programming 109 languages such as Ruby or Java may use libraries that automatically 110 promote JSON values to first order object attributes or members (e.g. 111 using the example above, the values may be referenced as 112 network.handle or network.lunarNic_beforeOneSmallStep). Second, a 113 clean mapping between JSON and XML is easy to accomplish using the 114 JSON representation. 116 Clients processing JSON responses MUST be prepared for values 117 specified in this document to be absent from a response as no JSON 118 value listed in this document is required to appear in the response. 119 In other words, servers MAY remove values as is needed by the 120 policies of the server operator. 122 4. Responses 124 As specified in RIR-QUERY [I-D.newton-et-al-weirds-rir-query], 125 queries for resources and information can be made for three types of 126 information: 1) information about IP networks, 2) information about 127 autonomous system numbers, and 3) information about reverse DNS 128 delegations. Queries for each of these three types can be 129 constructed to target specific information: 131 o operator information (e.g. "/operator") 133 o contacts of the operator (e.g "/operator/contacts") 135 o specific types of contacts of the operator (e.g. "/operator/ 136 contacts/abuse") 138 o registration information about the networks, AS numbers, or DNS 139 delegations (e.g. "/registration") 141 o all of the above (e.g. "/") 143 4.1. IP Networks 145 The following is an elided example of a JSON [RFC4627] response 146 object to a query for both registration and operator information of 147 an IP network 149 { 150 "network": 151 { 152 ... 153 }, 154 "operator": 155 { 156 ... 157 } 158 } 160 Figure 1 162 The "network" member, which may be queried for directly as the 163 registration information (i.e. "/registration") of the IP network is 164 described below. 166 The following is an example of the JSON object for the network 167 registration information 169 { 170 "handle" : "XXXX-RIR", 171 "startAddress" : "10.0.0.0", 172 "endAddress" : "10.0.0.255", 173 "ipVersion" : 4, 174 "name": "NET-RTR-1", 175 "description" : [ "A network used for routing" ], 176 "type" : "DIRECT ALLOCATION", 177 "country" : "AU", 178 "parentHandle" : "YYYY-RIR", 179 "remarks" : [ 180 "she sells seas shells", 181 "down by the seashore" 182 ], 183 "uris" : [ 184 { 185 "type" : "source", 186 "uri" : "http://whois-rws.net/network/xxxx" 187 }, 188 { 189 "type" : "parent", 190 "uri" : "http://whois-rws.net/network/yyyy" 191 }, 192 { 193 "type" : "held", 194 "uri" : "http://example.net/location/xxxx" 195 } 196 ], 197 "registrationDate" : "20110509", 198 "lastChangedDate" : "20110509", 199 "lastChangedBy" : "joe@bob.com" 200 } 202 The following is a description of the members of this object: 204 handle -- a string representing an RIR unique identifier of the 205 network registration 207 startAddress -- the starting IP address of the network, either IPv4 208 [RFC0791] or IPv6 [RFC5952] 210 endAddress -- the ending IP address of the network, either IPv4 or 211 IPv6 213 ipVersion -- an integer signifying the IP protocol version of the 214 network: 4 signifying an IPv4 network, 6 signifing an IPv6 network 216 name -- an identifier assigned to the network registration by the 217 registration holder 219 description -- an array of strings containing descriptive text about 220 the network registration 222 type -- a string containing an RIR specific classification of the 223 network 225 country -- a string containing the name of the country of the 226 network which MAY be in ISO 3166 2 character code [ISO.3166.1988] 227 format 229 parendHandle -- a string containing an RIR unique identifier of the 230 parent network of this network registration 232 The members "remarks", "uris", "registrationDate", "lastChangedDate", 233 and "lastChangedBy" take the same form of the members of the same 234 name of the entity object (Section 5). 236 The "operator" member of Figure 1, which maybe queried for directly 237 using the "/operator" path, is described below. 239 The following is an elided example of a JSON response object for 240 operator information 242 { 243 "entity": 244 { 245 ... 246 }, 247 "contacts": 248 { 249 "tech": [ 250 ... 251 ], 252 "admin": [ 253 ... 254 ], 255 "abuse": [ 256 ... 257 ] 258 } 259 } 261 Figure 2 263 The "entity" member of Figure 2 is an object and is specified in 264 Section 5. The "contacts" member is an object containing three 265 arrays: "tech", "admin", and "abuse". Each of these arrays contains 266 entities (Section 5). That is, the "tech" array contains entity 267 objects, each representing a tech contact, etc... 269 4.2. Autonomous Systems 271 An autonomous number query for both the registration and operator 272 and/or contact information yields an object containing an "autnum" 273 member and an "operator" member. The "operator" member is as 274 specified in Section 4.1. Additionally, queries specifically for the 275 operator and/or contact information take the same form as in 276 Section 4.1. 278 The "autnum" member mentioned above as well as queries directly for 279 the registration information take the form of a JSON [RFC4627] 280 object. 282 The following is an example of a JSON object representing an autnum. 284 { 285 "handle" : "XXXX-RIR", 286 "startAutnum" : "10", 287 "endAutnum" : "15", 288 "name": "AS-RTR-1", 289 "description" : [ "AS for Exchange" ], 290 "type" : "DIRECT ALLOCATION", 291 "country": "AU", 292 "remarks" : [ 293 "she sells seas shells", 294 "down by the seashore" 295 ], 296 "uris" : [ 297 { 298 "type" : "source", 299 "uri" : "http://whois-rws.net/autnum/xxxx" 300 }, 301 { 302 "type" : "parent", 303 "uri" : "http://whois-rws.net/autnum/yyyy" 304 }, 305 { 306 "type" : "held", 307 "uri" : "http://example.net/location/xxxx" 308 } 309 ], 310 "registrationDate" : "20110509", 311 "lastChangedDate" : "20110509", 312 "lastChangedBy" : "joe@bob.com" 313 } 315 The following is a description of the members of this object: 317 handle -- a string representing an RIR unique identifier of the 318 autnum registration 320 startAutnum -- the starting number [RFC5396] in the block of 321 autonomous system numbers 323 endAutnum -- the ending number [RFC5396] in the block of autonomous 324 system numbers 326 name an identifier assigned to the autnum registration by the 327 registration holder 329 description -- an array of strings containing descriptive text about 330 the autnum registration 332 type -- a string containing an RIR specific classification of the 333 autnum 335 country -- a string containing the name of the country of the autnum 336 which MAY be in ISO 3166 2 character code [ISO.3166.1988] format 338 The members "remarks", "uris", "registrationDate", "lastChangedDate", 339 and "lastChangedBy" take the same form of the members of the same 340 name of the entity object (Section 5). 342 4.3. Reverse DNS 344 A reverse DNS delegation query for both the registration and operator 345 and/or contact information yields an object containing an "rdns" 346 member and an "operator" member. The "operator" member is as 347 specified in Section 4.1. Additionally, queries specifically for the 348 operator and/or contact information take the same form as in 349 Section 4.1. 351 The "rdns" member mentioned above as well as queries directly for the 352 reverse DNS information take the form of a JSON [RFC4627] object. 354 The following is an example of a JSON object representing an reverse 355 DNS delegation. 357 { 358 "handle" : "XXXX-RIR", 359 "name" : "192.in-addr.arpa", 360 "nameServers" : [ "ns1.rir.net", "ns2.rir.net" ], 361 "delegationKeys" : [ 362 { 363 "algorithm": 7, 364 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 365 "digestType" : 1, 366 "keyTag" : 53814 367 } 368 ], 369 "remarks" : [ 370 "she sells seas shells", 371 "down by the seashore" 372 ], 373 "uris" : [ 374 { 375 "type" : "source", 376 "uri" : "http://whois-rws.net/network/xxxx" 377 }, 378 { 379 "type" : "parent", 380 "uri" : "http://whois-rws.net/network/yyyy" 381 }, 382 { 383 "type" : "held", 384 "uri" : "http://example.net/location/xxxx" 385 } 386 ], 387 "registrationDate" : "20110509", 388 "lastChangedDate" : "20110509", 389 "lastChangedBy" : "joe@bob.com" 390 } 392 The following is a description of the members of this object: 394 handle -- a string representing an RIR unique identifier of the 395 reverse DNS delegation 397 name -- a string denoting the DNS zone name, see [RFC4343] 399 nameservers -- an array of strings, each being a fully qualified DNS 400 name [RFC4343] of a namesever 402 delegationKeys -- an array of objects, each with the following 403 members: 405 algorithm -- an integer as specified by the algorithm field of a 406 DNS DS record as specified by RFC 4034 [RFC4034] in 407 presentation format 409 digest -- an string as specified by the digest field of a DNS DS 410 record as specified by RFC 4034 in presentation format 412 digestType -- an integer as specified by the digest type field of 413 a DNS DS record as specified by RFC 4034 in presetnation format 415 keyTag -- an integer as specified by the key tag field of a DNS 416 DS record as specified by RFC 4034 in presentation format 418 The members "remarks", "uris", "registrationDate", "lastChangedDate", 419 and "lastChangedBy" take the same form of the members of the same 420 name of the entity object (Section 5). 422 5. The Entity Object 424 Throughout this document there is a need to represent the identity 425 and contact information of organizations, corporations, governments, 426 non-profits, clubs, individual persons, and informal groups of 427 people. All of these representations are so similar that it is best 428 to represent them in JSON [RFC4627] with one construct, the entity 429 object, to aid in the re-use of code by implementers. 431 The following is an example of an entity: 433 { 434 "handle" : "XXXX-RIR", 435 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 436 "postalAddress" : [ 437 "123 Maple Ave", 438 "Suite 90001", 439 "Vancouver", 440 "BC", 441 "12393" 442 ], 443 "emails" : [ "joe@bob.com", "bob@joe.com" ], 444 "phones" : { 445 "office" : [ "999-999-999-99", "111-111-111-11" ], 446 "fax" : [ "222-222-222-22" ], 447 "mobile" : [ "333-333-333-33" ] 448 }, 449 "remarks" : [ 450 "she sells seas shells", 451 "down by the seashore" 452 ], 453 "uris" : [ 454 { 455 "type" : "source", 456 "uri" : "http://whois-rws.net/contact/xxxx" 457 }, 458 { 459 "type" : "held", 460 "uri" : "http://example.net/location/xxxx" 461 } 462 ], 463 "registrationDate" : "20110509", 464 "lastChangedDate" : "20110509", 465 "lastChangedBy" : "joe@bob.com" 466 } 468 This object as the following members. 470 handle -- a string representing an RIR unique identifier of the 471 entity 473 names -- an array of strings, each signifying the name of the entity 475 postalAddress -- an array of string, each representing a line in a 476 postal address. 478 emails -- an array of strings, each containing an email address 479 [RFC5322] for the entity 481 phones -- an object containg telephone information associated with 482 the entity, with the following members: 484 office -- an array of strings, each being a telephone number 486 fax -- an array of strings, each being a telephone number 488 mobile -- an array of strings, each being a telephone number 490 remarks -- an array of strings, each containing comments about the 491 entity 493 uris -- an array of objects, each object having the following 494 members: 496 type -- a string denoting the application type of the "uri" value 498 uri -- a string containing a URI [RFC3986] 500 registrationDate -- a string containing the date the entity was 501 registered, which SHOULD be in RFC 3339 [RFC3339] format 503 lastChangedDate -- a string containing the date of last change made 504 to the entity, which SHOULD be in RFC 3339 format 506 lastChangedBy -- a string containing an identifier of the party 507 responsible for the last change made to the entity registration 509 6. Normative References 511 [I-D.newton-et-al-weirds-rir-query] 512 Newton, A., Ranjbar, K., and A. Servin, "A Uniform RESTful 513 URL Query Pattern for RIRs", 514 draft-newton-et-al-weirds-rir-query-00 (work in progress), 515 September 2011. 517 [RFC4627] Crockford, D., "The application/json Media Type for 518 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 520 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 521 Internet: Timestamps", RFC 3339, July 2002. 523 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 524 Rose, "Resource Records for the DNS Security Extensions", 525 RFC 4034, March 2005. 527 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 528 September 1981. 530 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 531 Address Text Representation", RFC 5952, August 2010. 533 [ISO.3166.1988] 534 International Organization for Standardization, "Codes for 535 the representation of names of countries, 3rd edition", 536 ISO Standard 3166, August 1988. 538 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 539 Autonomous System (AS) Numbers", RFC 5396, December 2008. 541 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 542 Clarification", RFC 4343, January 2006. 544 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 545 Resource Identifier (URI): Generic Syntax", STD 66, 546 RFC 3986, January 2005. 548 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 549 October 2008. 551 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 552 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 553 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 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