idnits 2.17.1 draft-newton-et-al-weirds-rir-json-response-00.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 78: '...sponses, clients SHOULD put the "appli...' RFC 2119 keyword, line 79: '...header. Servers SHOULD respond with J...' RFC 2119 keyword, line 83: '... RECOMMENDED....' RFC 2119 keyword, line 87: '...g JSON responses SHOULD ignore values ...' RFC 2119 keyword, line 88: '... names. Servers MAY insert values sig...' (6 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 308 has weird spacing: '... name an id...' -- The document date (January 31, 2012) is 4469 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) No issues found here. Summary: 3 errors (**), 0 flaws (~~), 2 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: August 3, 2012 RIPE NCC 6 A. Servin 7 LACNIC 8 January 31, 2012 10 JSON Responses to RESTful URL Queries for RIRs 11 draft-newton-et-al-weirds-rir-json-response-00 13 Abstract 15 This document describes responses in the JSON format to the RESTful 16 queries described in draft-newton-et-al-weirds-rir-query. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 3, 2012. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Signalling for JSON . . . . . . . . . . . . . . . . . . . . . 4 54 3. JSON Naming . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 4.1. IP Networks . . . . . . . . . . . . . . . . . . . . . . . 6 57 4.2. Autonomous Systems . . . . . . . . . . . . . . . . . . . . 9 58 4.3. Reverse DNS . . . . . . . . . . . . . . . . . . . . . . . 11 59 5. The Entity Object . . . . . . . . . . . . . . . . . . . . . . 14 60 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 62 1. Introduction 64 The Regional Internet Registries (RIRs) have begun experimenting with 65 RESTful web services for access to Whois data. 66 draft-newton-et-al-weirds-rir-query presents uniform patterns which 67 may be used to contruct URLs for accessing data from these RESTful 68 web services. This document describes responses in the JSON 69 serialization format to the query URLs in 70 draft-newton-et-al-weirds-rir-query. 72 As this document describes responses returned in JSON format, other 73 documents may describe responses in other formats to the same URL 74 queries. 76 2. Signalling for JSON 78 To receive JSON responses, clients SHOULD put the "application/json" 79 MIME type in the Accept header. Servers SHOULD respond with JSON 80 responses when this MIME type is present in the Accept header in 81 accordance with the preference rules for the Accept header in HTTP, 82 however the use of multiple MIME types in the Accept header is NOT 83 RECOMMENDED. 85 3. JSON Naming 87 Clients processing JSON responses SHOULD ignore values associated 88 with unrecognized names. Servers MAY insert values signified by 89 names into the JSON responses which are not specified in this 90 document. Insertion of unspecified values into JSON responses SHOULD 91 have names prefixed with a short identifier followed by an underscore 92 followed by a meaningful name. 94 For example, "handle" is specified in this document as the name of a 95 value which is a string containing an RIR unique identifier for a 96 registration. The RIR of the Moon might desire to insert a value 97 specific to their services denoting that a registration occured 98 before or after the first moon landing. The name for such a value 99 might take the form "lunarNic_beforeOneSmallStep". 101 JSON names SHOULD NOT contain punctuation, whitespace, or other 102 characters typically not allowed in variable names of modern 103 programming languages. This better enables clients to automatically 104 promote JSON values to first order object attributes or members using 105 the given JSON names. Using the examples above, a Java or Ruby 106 programmer working with such a framework may be able to reference the 107 values as network.handle or network.lunarNic_beforeOneSmallStep. 109 Clients processing JSON responses MUST be prepared for values 110 specified in this document to be absent from a response as no JSON 111 value listed in this document is required to appear in the response. 112 In other words, servers MAY remove values as is needed by the 113 policies of the server operator. 115 4. Responses 117 As specified in draft-newton-et-al-weirds-rir-query, queries for 118 resources and information can be made for three types of information: 119 1) information about IP networks, 2) information about autonomous 120 system numbers, and 3) information about reverse DNS delegations. 121 Queries for each of these three types can be constructed to target 122 specific information: 124 o operator information (e.g. "/operator") 126 o contacts of the operator (e.g "/operator/contacts") 128 o specific types of contacts of the operator (e.g. "/operator/ 129 contacts/abuse") 131 o registration information about the networks, AS numbers, or DNS 132 delegations (e.g. "/registration") 134 o all of the above (e.g. "/") 136 4.1. IP Networks 138 The following is an elided example of a JSON response object to a 139 query for both registration and operator information of an IP network 141 { 142 "network": 143 { 144 ... 145 }, 146 "operator": 147 { 148 ... 149 } 150 } 152 Figure 1 154 The "network" member, which may be queried for directly as the 155 registration information (i.e. "/registration") of the IP network is 156 described below. 158 The following is an example of the JSON object for the network 159 registration information 161 { 162 "handle" : "XXXX-RIR", 163 "startAddress" : "10.0.0.0", 164 "endAddress" : "10.0.0.255", 165 "ipVersion" : 4, 166 "name": "NET-RTR-1", 167 "description" : "A network used for routing", 168 "type" : "DIRECT ALLOCATION", 169 "parentId" : "YYYY-RIR", 170 "remarks" : [ 171 "she sells seas shells", 172 "down by the seashore" 173 ], 174 "uris" : [ 175 { 176 "type" : "source", 177 "uri" : "http://whois-rws.net/network/xxxx" 178 }, 179 { 180 "type" : "parent", 181 "uri" : "http://whois-rws.net/network/yyyy" 182 }, 183 { 184 "type" : "held", 185 "uri" : "http://example.net/location/xxxx" 186 } 187 ], 188 "registrationDate" : "20110509", 189 "lastChangedDate" : "20110509", 190 "lastChangedBy" : "joe@bob.com" 191 } 193 The following is a description of the members of this object: 195 handle -- a string representing an RIR unique identifier of the 196 network registration 198 startAddress -- the starting IP address of the network 200 endAddress -- the ending IP address of the network 201 ipVersion -- an integer signifying the IP protocol version of the 202 network: 4 signifying an IPv4 network, 6 signifing an IPv6 network 204 name -- an identifier assigned to the network registration by the 205 registration holder 207 description -- a string containing descriptive text about the 208 network registration 210 type -- a string containing an RIR specific classification of the 211 network 213 parendId -- a string containing an RIR unique identifier of the 214 parent network of this network registration 216 The members "remarks", "uris", "registrationDate", "lastChangedDate", 217 and "lastChangedBy" take the same form of the members of the same 218 name of the entity object (Section 5). 220 The "operator" member of Figure 1, which maybe queried for directly 221 using the "/operator" path, is described below. 223 The following is an elided example of a JSON response object for 224 operator information 226 { 227 "entity": 228 { 229 ... 230 }, 231 "contacts": 232 { 233 "tech": [ 234 ... 235 ], 236 "admin": [ 237 ... 238 ], 239 "abuse": [ 240 ... 241 ] 242 } 243 } 245 Figure 2 247 The "entity" member of Figure 2 is an object and is specified in 248 Section 5. The "contacts" member is an object containing three 249 arrays: "tech", "admin", and "abuse". Each of these arrays contains 250 entities (Section 5). That is, the "tech" array contains entity 251 objects, each representing a tech contact, etc... 253 4.2. Autonomous Systems 255 An autonomous number query for both the registration and operator 256 and/or contact information yields an object containing an "autnum" 257 member and an "operator" member. The "operator" member is as 258 specified in Section 4.1. Additionally, queries specifically for the 259 operator and/or contact information take the same form as in 260 Section 4.1. 262 The "autnum" member mentioned above as well as queries directly for 263 the registration information take the form of a JSON object. 265 The following is an example of a JSON object representing an autnum. 267 { 268 "handle" : "XXXX-RIR", 269 "startAutnum" : "10", 270 "endAutnum" : "15", 271 "name": "AS-RTR-1", 272 "description" : "AS for Exchange", 273 "type" : "DIRECT ALLOCATION", 274 "remarks" : [ 275 "she sells seas shells", 276 "down by the seashore" 277 ], 278 "uris" : [ 279 { 280 "type" : "source", 281 "uri" : "http://whois-rws.net/autnum/xxxx" 282 }, 283 { 284 "type" : "parent", 285 "uri" : "http://whois-rws.net/autnum/yyyy" 286 }, 287 { 288 "type" : "held", 289 "uri" : "http://example.net/location/xxxx" 290 } 291 ], 292 "registrationDate" : "20110509", 293 "lastChangedDate" : "20110509", 294 "lastChangedBy" : "joe@bob.com" 295 } 297 The following is a description of the members of this object: 299 handle -- a string representing an RIR unique identifier of the 300 autnum registration 302 startAutnum -- the starting number in the block of autonomous system 303 numbers 305 endAddress -- the ending number in the block of autonomous system 306 numbers 308 name an identifier assigned to the autnum registration by the 309 registration holder 311 description -- a string containing descriptive text about the autnum 312 registration 314 type -- a string containing an RIR specific classification of the 315 autnum 317 The members "remarks", "uris", "registrationDate", "lastChangedDate", 318 and "lastChangedBy" take the same form of the members of the same 319 name of the entity object (Section 5). 321 4.3. Reverse DNS 323 A reverse DNS delegation query for both the registration and operator 324 and/or contact information yields an object containing an "rdns" 325 member and an "operator" member. The "operator" member is as 326 specified in Section 4.1. Additionally, queries specifically for the 327 operator and/or contact information take the same form as in 328 Section 4.1. 330 The "rdns" member mentioned above as well as queries directly for the 331 reverse DNS information take the form of a JSON object. 333 The following is an example of a JSON object representing an autnum. 335 { 336 "handle" : "XXXX-RIR", 337 "name" : "192.in-addr.arpa", 338 "nameServers" : [ "ns1.rir.net", "ns2.rir.net" ], 339 "delegationKeys" : [ 340 { 341 "algorithm": 7, 342 "digest" : "E68C017BD813B9AE2F4DD28E61AD014F859ED44C", 343 "digestType" : 1, 344 "keyTag" : 53814 345 } 346 ], 347 "remarks" : [ 348 "she sells seas shells", 349 "down by the seashore" 350 ], 351 "uris" : [ 352 { 353 "type" : "source", 354 "uri" : "http://whois-rws.net/network/xxxx" 355 }, 356 { 357 "type" : "parent", 358 "uri" : "http://whois-rws.net/network/yyyy" 359 }, 360 { 361 "type" : "held", 362 "uri" : "http://example.net/location/xxxx" 363 } 364 ], 365 "registrationDate" : "20110509", 366 "lastChangedDate" : "20110509", 367 "lastChangedBy" : "joe@bob.com" 368 } 370 The following is a description of the members of this object: 372 handle -- a string representing an RIR unique identifier of the 373 autnum registration 375 name -- a string denoting the DNS zone 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 in presentation format 385 digest -- an string as specified by the digest field of a DNS DS 386 record as specified by RFC 4034 in presentation format 388 digestType -- an integer as specified by the digest type field of 389 a DNS DS record as specified by RFC 4034 in presetnation format 391 keyTag -- an integer as specified by the key tag field of a DNS 392 DS record as specified by RFC 4034 in presentation format 394 The members "remarks", "uris", "registrationDate", "lastChangedDate", 395 and "lastChangedBy" take the same form of the members of the same 396 name of the entity object (Section 5). 398 5. The Entity Object 400 Throughout this document there is a need to represent the identity 401 and contact information of organizations, corporations, governments, 402 non-profits, clubs, individual persons, and informal groups of 403 people. All of these representations are so similar that it is best 404 to represent them in JSON with one construct, the entity object. 405 Such re-use is beleived to aid in the re-use of code by implementers. 407 The following is an example of an entity: 409 { 410 "handle" : "XXXX-RIR", 411 "names": [ "Joe Bob, Inc.", "Bobby Joe Shopping" ], 412 "postalAddress" : [ 413 "123 Maple Ave", 414 "Suite 90001", 415 "Vancouver", 416 "BC", 417 "12393" 418 ], 419 "emails" : [ "joe@bob.com", "bob@joe.com" ], 420 "phones" : { 421 "office" : [ "999-999-999-99", "111-111-111-11" ], 422 "fax" : [ "222-222-222-22" ], 423 "mobile" : [ "333-333-333-33" ] 424 }, 425 "remarks" : [ 426 "she sells seas shells", 427 "down by the seashore" 428 ], 429 "uris" : [ 430 { 431 "type" : "source", 432 "uri" : "http://whois-rws.net/contact/xxxx" 433 }, 434 { 435 "type" : "held", 436 "uri" : "http://example.net/location/xxxx" 437 } 438 ], 439 "registrationDate" : "20110509", 440 "lastChangedDate" : "20110509", 441 "lastChangedBy" : "joe@bob.com" 442 } 444 This object as the following members. 446 handle -- a string representing an RIR unique identifier of the 447 entity 449 names -- an array of strings, each signifying the name of the entity 451 postalAddress -- an array of string, each representig a line in a 452 postal address. 454 emails -- an array of strings, each containing an email address for 455 the entity 457 phones -- an object containg telephone information associated with 458 the entity, with the following members: 460 office -- an array of strings, each being a telephone number 462 fax -- an array of strings, each being a telephone number 464 mobile -- an array of strings, each being a telephone number 466 remarks -- an array of strings, each containing comments about the 467 entity 469 uris -- an array of objects, each object having the following 470 members: 472 type -- a string denoting the application type of the "uri" value 474 uri -- a string containing a URI 476 registrationDate -- a string containing the date the entity was 477 registered, which SHOULD be in RFC 3339 format 479 lastChangedDate -- a string containing the date of last change made 480 to the entity, which SHOULD be in RFC 3339 format 482 lastChangedBy -- a string containing an identifier of the party 483 responsible for the last change made to the entity registration 485 Authors' Addresses 487 Andrew Lee Newton 488 American Registry for Internet Numbers 489 3635 Concorde Parkway 490 Chantilly, VA 20151 491 US 493 Email: andy@arin.net 494 URI: http://www.arin.net 496 Kaveh Ranjbar 497 RIPE Network Coordination Centre 498 Singel 258 499 Amsterdam 1016AB 500 NL 502 Email: kranjbar@ripe.net 503 URI: http://www.ripe.net 505 Arturo L. Servin 506 Latin American and Caribbean Internet Address Registry 507 Rambla Republica de Mexico 6125 508 Montevideo 11300 509 UY 511 Email: aservin@lacnic.net 512 URI: http://www.lacnic.net