idnits 2.17.1 draft-kong-dnrd-ap-response-json-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o transferDate -- the date and time of the most recent successful transfer. The date and time values MUST be represented in Universal Coordinated Time (UTC). If no tranfer occurs, this key MUST not be provided. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o transferDate -- the date and time of the most recent successful transfer. The date and time values MUST be represented in Universal Coordinated Time (UTC). If no tranfer occurs, this key MUST not be provided. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o transferDate -- the date and time of the most recent successful transfer. The date and time values MUST be represented in Universal Coordinated Time (UTC). If no tranfer occurs, this key MUST not be provided. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o transferDate -- the date and time of the most recent successful transfer. The date and time values MUST be represented in Universal Coordinated Time (UTC). If no tranfer occurs, this key MUST not be provided. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 3, 2012) is 4345 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: 'RFC5730' is defined on line 839, but no explicit reference was found in the text == Unused Reference: 'RFC5732' is defined on line 842, but no explicit reference was found in the text == Unused Reference: 'RFC5733' is defined on line 845, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMA-262' -- Possible downref: Non-RFC (?) normative reference: ref. 'REST' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force N. Kong 3 Internet-Draft L. Zhou 4 Intended status: Standards Track J. Xie 5 Expires: December 5, 2012 S. Shen 6 CNNIC 7 June 3, 2012 9 Domain Name Registration Data Access Protocol Response Format defined in 10 JSON 11 draft-kong-dnrd-ap-response-json-00 13 Abstract 15 This document describes a response format for registration data 16 (Whois data) through RESTful Web-based Service. This response format 17 is defined in JavaScript Object Notation (JSON). 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on December 5, 2012. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Convention Used in This Document . . . . . . . . . . . . . . . 3 67 2.1. Abbreviations and Terminology . . . . . . . . . . . . . . 3 68 3. Response Format Specification . . . . . . . . . . . . . . . . 4 69 3.1. Domain Name Response Specification . . . . . . . . . . . . 4 70 3.1.1. Objects in the Domain Name Response . . . . . . . . . 5 71 3.1.2. Extension Interface . . . . . . . . . . . . . . . . . 7 72 3.1.3. JSON Format . . . . . . . . . . . . . . . . . . . . . 7 73 3.2. Nameserver Response Specification . . . . . . . . . . . . 9 74 3.2.1. Objects in the Nameserver Response . . . . . . . . . . 9 75 3.2.2. Extension Interface . . . . . . . . . . . . . . . . . 10 76 3.2.3. JSON Format . . . . . . . . . . . . . . . . . . . . . 10 77 3.3. Contact Response Specification . . . . . . . . . . . . . . 11 78 3.3.1. Objects in the Contact Response . . . . . . . . . . . 12 79 3.3.2. Extension Interface . . . . . . . . . . . . . . . . . 13 80 3.3.3. JSON Format . . . . . . . . . . . . . . . . . . . . . 13 81 3.4. Registrar Response Specification . . . . . . . . . . . . . 14 82 3.4.1. Objects in the Registrar Response . . . . . . . . . . 15 83 3.4.2. Extension Interface . . . . . . . . . . . . . . . . . 16 84 3.4.3. JSON Format . . . . . . . . . . . . . . . . . . . . . 17 85 4. Accept Header . . . . . . . . . . . . . . . . . . . . . . . . 19 86 5. Internationalization Considerations . . . . . . . . . . . . . 19 87 5.1. Encoding Specification . . . . . . . . . . . . . . . . . . 19 88 5.2. IDN Variants . . . . . . . . . . . . . . . . . . . . . . . 19 89 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 90 7. Security considerations . . . . . . . . . . . . . . . . . . . 19 91 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 19 92 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 93 9.1. Normative References . . . . . . . . . . . . . . . . . . . 20 94 9.2. Informative References . . . . . . . . . . . . . . . . . . 20 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 97 1. Introduction 99 Internet registries for both number resources and names have 100 historically maintained a lookup service to permit public access to 101 some portion of the registry database. Most registries offer the 102 service via the WHOIS protocol [RFC3912], with additional services 103 being offered via world wide web pages, bulk downloads, and other 104 services, such as RPSL [RFC2622]. 106 Although the WHOIS protocol specified in [RFC3912] is widely adopted 107 and supported, it has several shortcomings that limits its usefulness 108 to the evolving needs of the Internet community. For example, the 109 WHOIS protocol has not been Internationalized, it does not 110 consistently support Internationalized Domain Name (IDN, described in 111 [RFC5890]); WHOIS has no query and response format; and WHOIS 112 protocol does not support user authentication, access control for 113 differentiated access. 115 Recently, the Internet Engineering Task Force (IETF) chartered a new 116 working group to standardize a web-based (RESTful) Extensible 117 Registration Data Access Protocol. This document, to be read in 118 conjunction with the RESTful Query draft 119 [draft-hollenbeck-dnrd-ap-query-01], describes the response 120 specification for querying registration data through RESTful web 121 service. 123 The response formats for querying domain, contact, nameserver name 124 and registrar are defined in JSON, which is specified based on a 125 subset of the JavaScript Programming Language, Standard ECMA-262 3rd 126 Edition - December 1999 ([ECMA-262]) and [RFC4627]. 128 2. Convention Used in This Document 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in [RFC2119]. 134 2.1. Abbreviations and Terminology 136 Domain Name Registration Data (DNRD) - refers to the information that 137 registrants provide when registering a domain name. Registrars and 138 registries collect this information and typically make a subset 139 available to the public via the Whois service. 141 JavaScript Object Notation (JSON) is a lightweight data-interchange 142 format. It is based on a subset of the JavaScript Programming 143 Language, Standard ECMA-262 3rd Edition - December 1999 ([ECMA-262]) 144 and [RFC4627]. 146 Representational state transfer (REST) is a software architecture 147 style for distributed systems such as the World Wide Web (Chapter 5 148 of Fielding's dissertation is [REST]). 150 RESTful web service is a web service implemented using HTTP and the 151 principles of REST. It is a collection of resources, with four 152 defined aspects: 154 o The base URI for the web service, such as 155 http://example.com/resources/. 157 o The Internet media type of the data supported by the web service. 158 This is often JSON, XML or YAML but can be any other valid 159 Internet media type. 161 o The set of operations supported by the web service using HTTP 162 methods (e.g., GET, PUT, POST, or DELETE). 164 o The API must be hypertext driven. 166 3. Response Format Specification 168 This section describes the response format specification for querying 169 domain name, nameserver, contact and registrar. The specific format 170 is defined in JSON. The basic querying URLs are described in the 171 draft-hollenbeck-dnrd-ap-query-01. 173 The following response objects defined MAY be supported optionally by 174 each registry. Clients processing JSON responses MUST be prepared 175 for values specified in this document to be absent from a response as 176 no JSON value listed in this document is required to appear in the 177 response. In other words, the server can remove the values as is 178 needed by the policy of the registries. 180 3.1. Domain Name Response Specification 182 This section gives the set of required information and format that 183 SHOULD be included in the domain name responses. An extension 184 interface MAY also be defined for customized response information. 186 The corresponding querying URI example is: 188 http://example.com/dnrd-ap/domain/example.com/ or 189 http://example.com/dnrd-ap/example.com/ 190 The following is an elided example of a JSON response for a domain 191 query: 193 { 194 "domain": { 195 ... 196 }, 197 "nameserver": [ 198 ... 199 ], 200 "contact": [ 201 ... 202 ], 203 "registrar": { 204 ... 205 }, 206 "extension": { 207 ... 208 } 209 } 211 3.1.1. Objects in the Domain Name Response 213 There are "domain", "nameserver", "contact", "registrar" and 214 "extension" objects included in the domain response. The followings 215 are description and explanation of objects members. 217 domain -- contains the information about the domain. The members of 218 domain object are defined as below. 220 o domainName -- contains the fully qualified name of the registered 221 domain. 223 o roid -- the identifier assigned to the domain name when the object 224 was created. 226 o domainStatus -- an array contains the current status values 227 defined in [RFC5731]. 229 o clientID -- element that contains the identifier of the sponsoring 230 client. 232 o createID -- contains the identifier of the client that created the 233 domain. 235 o creationDate -- the date and time when the domain name is 236 registered. The date and time values MUST be represented in 237 Universal Coordinated Time (UTC). 239 o expirationDate -- the date and time when the domain name is 240 expiry. The date and time values MUST be represented in Universal 241 Coordinated Time (UTC). 243 o updateID -- contains the identifier of the client that updated the 244 domain. 246 o updateDate -- the date and time when the domain name is updated. 247 The date and time values MUST be represented in Universal 248 Coordinated Time (UTC). 250 o transferDate -- the date and time of the most recent successful 251 transfer. The date and time values MUST be represented in 252 Universal Coordinated Time (UTC). If no tranfer occurs, this key 253 MUST not be provided. 255 o dnssec -- the status of DNSSEC deployment. A value of "Signed" or 256 "Yes" means that DNSSEC has been deployed. A value of "Unsigned" 257 or "No" means that DNSSEC has not been deployed yet. 259 nameserver -- an array that contains the information about the 260 nameserver or host. If the array object is a nameserver, 261 "namerserverName" and "nameserverUri" SHOULD be the members of the 262 array object. If the array object is a host, "host" and "hostUri" 263 SHOULD be the members of the array object. Nameserver information is 264 specified before host information. The members of nameserver object 265 are defined as below. 267 o nameserverName -- the fully qualified names of the delegated host 268 objects. 270 o nameserverUri -- the access address for detailed information about 271 nameserver. 273 o host -- contains the fully qualified names of the subordinate host 274 objects that exist under this superordinate domain object. 276 o hostUri -- the access address for detailed information about 277 hosts. 279 contact -- an array that contains the information about the contacts. 280 There are 4 types of contacts, including "registrant", "admin", 281 "tech" and "billing" JSON objects. The members of contact object are 282 defined as below. 284 o type -- the type of contact. They are "registrant", "admin", 285 "tech" and "billing". 287 o contactID -- the identifier of registrant, administrative contact, 288 technical contact or billing contact. 290 o contactUri -- the access address for detailed information about 291 registrant, administrative contact, technical contact or billing 292 contact. 294 registrar -- contains the information about the registrar. The 295 members of registrar object are defined as below. 297 o sponsoringRegistrar -- the name of the corresponding registrar. 299 o registrarUri - the access address for detailed information about 300 registrar. 302 3.1.2. Extension Interface 304 A "Extension" key SHOULD be included in the JSON format for 305 customized extension information of each registry. 307 3.1.3. JSON Format 309 { 310 "domain": { 311 "domainName": "example.com", 312 "roid": "20030310s10001s00012956", 313 "domainStatus": [ 314 "serverDeleteProhibited", 315 "serverUpdateProhibited", 316 "serverTransferProhibited" 317 ], 318 "clientID": "ClientX", 319 "createID": "ClientY", 320 "creationDate": "2003-03-10T19:06:00Z", 321 "expirationDate": "2018-03-10T19:06:00Z", 322 "updateID": "ClientX", 323 "updateDate": "2006-03-10T19:06:00Z", 324 "transferDate": "", 325 "dnssec": "Unsigned" 326 }, 327 "nameserver": [ 328 { 329 "nameserverName": "ns1.example.com", 330 "nameserverUri": 331 "http://example.com/dnrd-ap/nameserver/ns1.example.com/" 332 }, 333 { 334 "nameserverName": "ns2.example.com", 335 "nameserverUri": 336 "http://example.com/dnrd-ap/nameserver/ns2.example.com/" 337 }, 338 { 339 "nameserverName": "ns3.example.com", 340 "nameserverUri": 341 "http://example.com/dnrd-ap/nameserver/ns3.example.com/" 342 }, 343 { 344 "host": "ns1.example.com", 345 "hostUri": 346 "http://example.com/dnrd-ap/nameserver/ns1.example.com/" 347 }, 348 { 349 "host": "ns2.example.com", 350 "hostUri": 351 "http://example.com/dnrd-ap/nameserver/ns2.example.com/" 352 }, 353 { 354 "host": "ns3.example.com", 355 "hostUri": 356 "http://example.com/dnrd-ap/nameserver/ns3.example.com/" 357 } 358 ], 359 "contact": [ 360 { 361 "type": "registrant", 362 "contactID": "xyz", 363 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 364 }, 365 { 366 "type": "admin", 367 "contactID": "xyz", 368 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 369 }, 370 { 371 "type": "tech", 372 "contactID": "xyz", 373 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 374 }, 375 { 376 "type": "billing", 377 "contactID": "xyz", 378 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 379 } 380 ], 381 "registrar": { 382 "sponsoringRegistrar": "ABCRegistrar", 383 "registrarUri": "http://example.com/dnrd-ap/registrar/ABCRegistrar/" 384 }, 385 "extension": { 386 ... 387 } 388 } 390 3.2. Nameserver Response Specification 392 This section gives the set of required information and format that 393 SHOULD be included in the nameserver responses. An extension 394 interface MAY also be defined for customized response information. 396 The corresponding querying URL is: 398 http://example.com/dnrd-ap/nameserver/ns1.example.com/ 400 The following is an elided example of a JSON response for a 401 nameserver query: 403 { 404 "nameserver": { 405 ... 406 }, 407 "extension": { 408 ... 409 } 410 } 412 3.2.1. Objects in the Nameserver Response 414 nameserver -- contains the information about the domain. The members 415 of nameserver object are defined as below. 417 o roid -- the identifier assigned to the host object. 419 o nameserverName -- contains the fully qualified names of the 420 delegated host objects. 422 o nameserverStatus -- the status of host object. 424 o ipAddress -- contains the IPv4, IPv6, or both addresses. 426 o clientID -- element that contains the identifier of the sponsoring 427 client. 429 o createID -- contains the identifier of the client that created the 430 nameserver. 432 o creationDate -- the date and time when the nameserver is 433 registered. The date and time values MUST be represented in 434 Universal Coordinated Time (UTC). 436 o updateID -- contains the identifier of the client that updated the 437 domain. 439 o updateDate -- the date and time when the nameserver is updated. 440 The date and time values MUST be represented in Universal 441 Coordinated Time (UTC). 443 o transferDate -- the date and time of the most recent successful 444 transfer. The date and time values MUST be represented in 445 Universal Coordinated Time (UTC). If no tranfer occurs, this key 446 MUST not be provided. 448 3.2.2. Extension Interface 450 A "Extension" key SHOULD be included in the JSON format for 451 customized extension information of each registry. 453 3.2.3. JSON Format 454 { 455 "nameserver": { 456 "roid": "host397232", 457 "nameserverName": "ns1.example.com", 458 "nameserverStatus": [ 459 "serverDeleteProhibited", 460 "serverUpdateProhibited" 461 ], 462 "ipAddress":[ 463 "192.0.2.123", 464 "2001:0DB8::1" 465 ], 466 "clientID": "ClientX", 467 "createID": "ClientY", 468 "creationDate": "2006-09-27T09:27:00Z", 469 "updateID": "ClientX", 470 "updateDate": "2007-10-27T09:27:00Z", 471 "transferDate": "" 472 }, 473 "extension": { 474 ... 475 } 476 } 478 3.3. Contact Response Specification 480 This section gives the set of required information and format that 481 SHOULD be included in the contact responses. An extension interface 482 MAY also be defined for customized response information. 484 The corresponding querying URL is: 486 http://example.com/dnrd-ap/contact/CID-4005/ 488 The following is an elided example of a JSON response for a contact 489 query: 491 { 492 "contact": { 493 ... 494 }, 495 "extension": { 496 ... 497 } 498 } 500 3.3.1. Objects in the Contact Response 502 contact -- contains the information about the contacts. The members 503 of contact object are defined as below. 505 o contactID -- contains the identifier of the contact. 507 o roid -- contains the repository object identifier assigned to the 508 contact. 510 o contactStatus -- gives the status of the contact. 512 o postalInfo -- contains the post and address information. Both 513 internationalized and local addresses can be provided in this 514 object. A "type" member is defined with the value of "int" to 515 indicate internationalize address, and "loc" to indicate local 516 address. 518 * type -- contains the type of address, "int" is 519 internationalized adrress, "loc" is local address. 521 * contactName -- the name of the individual represented by the 522 contact. 524 * organization -- the group or company that the contact works 525 for. 527 * address -- contains the detailed address information. 529 + street -- the street of the contact's address. 531 + stateOrProvince -- the state or province of the contact's 532 address. 534 + postalCode -- the postal code of the contact's address. 536 + countryCode -- the contact's contry code. 538 o phoneNumber -- contains the contact's phone number. 540 o faxNumber -- contains the contact's fax number. 542 o email -- the email adress of the contact. 544 o clientID -- element that contains the identifier of the sponsoring 545 client. 547 o createID -- contains the identifier of the client that created the 548 contact. 550 o creationDate -- the date and time when the contact is created. 551 The date and time values MUST be represented in Universal 552 Coordinated Time (UTC). 554 o updateID -- contains the identifier of the client that updated the 555 contact. 557 o updateDate -- the date and time when the contact is updated. The 558 date and time values MUST be represented in Universal Coordinated 559 Time (UTC). 561 o transferDate -- the date and time of the most recent successful 562 transfer. The date and time values MUST be represented in 563 Universal Coordinated Time (UTC). If no tranfer occurs, this key 564 MUST not be provided. 566 3.3.2. Extension Interface 568 A "Extension" key SHOULD be included in the JSON format for 569 customized extension information of each registry. 571 3.3.3. JSON Format 572 { 573 "contact": { 574 "contactID": "CID-4005", 575 "roid": "CID-4005-REP", 576 "contactStatus": [ 577 "ok", 578 "linked" 579 ], 580 "postalInfo": [ 581 { 582 "type": "int", 583 "contactName": "Smith", 584 "organization": "ABC Corp.", 585 "address": { 586 "street": "South 4th Street", 587 "stateOrProvince": "CN", 588 "postalCode": "100000", 589 "countryCode": "CN" 590 } 591 } 592 ], 593 "phoneNumber": "+001.8002250180", 594 "faxNumber": "+001.8002250180", 595 "email": "domainadmin@example.com", 596 "clientID": "ClientX", 597 "createID": "ClientY", 598 "creationDate": "2006-09-27T09:27:00Z", 599 "updateID": "ClientX", 600 "updateDate": "2007-10-27T09:27:00Z", 601 "transferDate": "" 602 }, 603 "extension":{ 604 ... 605 } 606 } 608 3.4. Registrar Response Specification 610 This section gives the set of required information and format that 611 SHOULD be included in the contact responses. An extension interface 612 MAY also be defined for customized response information. 614 The corresponding querying URL is: 616 http://example.com/dnrd-ap/registrar/Example Registrar, Inc./ 618 The following is an elided example of a JSON response for a registrar 619 query: 621 { 622 "registrar": { 623 ... 624 }, 625 "registrarContact": [ 626 ... 627 ], 628 "extension": { 629 ... 630 } 631 } 633 3.4.1. Objects in the Registrar Response 635 registrar -- contains the information about the registrar. The 636 members of registrar object are defined as below. 638 o registrarIANAID -- contains the registrar ID specified by IANA. 640 o postalInfo -- contains the post and address information. Both 641 internationalized and local addresses can be provided in this 642 object. A "type" member is defined with the value of "int" to 643 indicate internationalize address, and "loc" to indicate local 644 address. 646 * type -- contains the type of address, "int" is 647 internationalized adrress, "loc" is local address. 649 * registrarName -- the name of the group or company represented 650 by the registrar. 652 * organization - the group or company that the contact works for. 654 * address -- contains the detailed address information. 656 + street -- the street of the registrar's address. 658 + stateOrProvince -- the state or province of the registrar's 659 address. 661 + postalCode -- the postal code of the registrar's address. 663 + countryCode -- the registrar's country code. 665 o phoneNumber -- contains the contact's phone registrar. 667 o faxNumber -- contains the contact's fax registrar. 669 o email -- the email address of the registrar. 671 o clientID -- element that contains the identifier of the sponsoring 672 client. 674 o createID -- contains the identifier of the client that created the 675 registrar. 677 o creationDate -- the date and time when the registrar is created. 678 The date and time values MUST be represented in Universal 679 Coordinated Time (UTC). 681 o updateID -- contains the identifier of the client that updated the 682 registrar. 684 o updateDate -- the date and time when the registrar is updated. 685 The date and time values MUST be represented in Universal 686 Coordinated Time (UTC). 688 o transferDate -- the date and time of the most recent successful 689 transfer. The date and time values MUST be represented in 690 Universal Coordinated Time (UTC). If no tranfer occurs, this key 691 MUST not be provided. 693 registrarContact -- an array contains the information of contacts 694 associated with the registrar. 696 o type -- the type of contact. They are "admin", "tech" and 697 "billing". 699 o contactID -- the identifier of administrative contact, technical 700 contact or billing contact. 702 o contactUri -- the access address for detailed information about 703 administrative contact, technical contact or billing contact. 705 3.4.2. Extension Interface 707 A "Extension" key SHOULD be included in the JSON format for 708 customized extension information of each registry. 710 3.4.3. JSON Format 711 { 712 "registrar": { 713 "registrarIANAID": "registrar1234", 714 "postalInfo": [ 715 { 716 "type": "int", 717 "registrarName": "Example Registrar, Inc.", 718 "organization": "Example Corp.", 719 "address": { 720 "street": "South 4th Street", 721 "stateOrProvince": "CN", 722 "postalCode": "100000", 723 "countryCode": "CN" 724 } 725 } 726 ], 727 "phoneNumber": "+001.8002250180", 728 "faxNumber": "+001.8002250180", 729 "email": "domainadmin@example.com", 730 "clientID": "ClientX", 731 "createID": "ClientY", 732 "creationDate": "2006-09-27T09:27:00Z", 733 "updateID": "ClientX", 734 "updateDate": "2007-10-27T09:27:00Z", 735 "transferDate": "" 736 }, 737 "registrarContact": [ 738 { 739 "type": "admin", 740 "contactID": "xyz", 741 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 742 }, 743 { 744 "type": "tech", 745 "contactID": "xyz", 746 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 747 }, 748 { 749 "type": "billing", 750 "contactID": "xyz", 751 "contactUri": "http://example.com/dnrd-ap/contact/xyz/" 752 } 753 ], 754 "extension":{ 755 ... 756 } 757 } 759 4. Accept Header 761 Clients MAY use a MIME type, such as "application/json" to desire the 762 JSON format of response. The server SHOULD respond the client with 763 the proper MIME type in the accept header, and give the above 764 response in JSON format. 766 5. Internationalization Considerations 768 5.1. Encoding Specification 770 The response format MUST has a key for defining encoding format, such 771 as "encoding", to explicitly demonstrate the character encoding that 772 the server can support. Both the U-label and A-label domain names 773 can be included in the response. 775 5.2. IDN Variants 777 Internationalized Domain Names (IDNs), particularly variants, brought 778 about the need for multiple domain names to be registered and managed 779 as a single package, or registration bundle. The bundle variant 780 domain names share some attributes, such as expiration date and the 781 registrar. So when users update any properties within a bundle, all 782 of the domains' attributes in the bundle will be changed. 784 The response SHOULD be able to be extended to support the IDN 785 variants to show the list of the bundle variant domain names. 787 6. IANA Considerations 789 This document does not specify any IANA actions. 791 7. Security considerations 793 TBD 795 8. Acknowledgements 797 This document has been reviewed and improved by the design team. The 798 authors especially thank the following individuals who gave their 799 suggestions and contributions to this document: Andy Newton and Steve 800 Sheng. 802 9. References 804 9.1. Normative References 806 [ECMA-262] 807 "ECMAScript Language Specification", June 2011, . 811 [REST] Fielding, R., "Architectural Styles and the Design of 812 Network-based Software Architectures", June 2000, . 816 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 817 Requirement Levels", BCP 14, RFC 2119, March 1997. 819 [RFC2622] Alaettinoglu, C., Villamizar, C., Gerich, E., Kessens, D., 820 Meyer, D., Bates, T., Karrenberg, D., and M. Terpstra, 821 "Routing Policy Specification Language (RPSL)", RFC 2622, 822 June 1999. 824 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 825 September 2004. 827 [RFC4627] Crockford, D., "The application/json Media Type for 828 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 830 [RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 831 Domain Name Mapping", STD 69, RFC 5731, August 2009. 833 [RFC5890] Klensin, J., "Internationalized Domain Names for 834 Applications (IDNA): Definitions and Document Framework", 835 RFC 5890, August 2010. 837 9.2. Informative References 839 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 840 STD 69, RFC 5730, August 2009. 842 [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 843 Host Mapping", STD 69, RFC 5732, August 2009. 845 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 846 Contact Mapping", STD 69, RFC 5733, August 2009. 848 Authors' Addresses 850 Ning Kong 851 CNNIC 852 4 South 4th Street, Zhongguancun, Haidian District 853 Beijing, Beijing 100190 854 China 856 Phone: +86 10 5881 3147 857 Email: nkong@cnnic.cn 859 Linlin Zhou 860 CNNIC 861 4 South 4th Street, Zhongguancun, Haidian District 862 Beijing, Beijing 100190 863 China 865 Phone: +86 10 5881 2677 866 Email: zhoulinlin@cnnic.cn 868 Jiagui Xie 869 CNNIC 870 4 South 4th Street, Zhongguancun, Haidian District 871 Beijing, Beijing 100190 872 China 874 Phone: +86 10 5881 2639 875 Email: xiejiagui@cnnic.cn 877 Sean Shen 878 CNNIC 879 4 South 4th Street, Zhongguancun, Haidian District 880 Beijing, Beijing 100190 881 China 883 Phone: +86 10 5881 3038 884 Email: shenshuo@cnnic.cn