idnits 2.17.1 draft-sheng-weirds-icann-rws-dnrd-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 : ---------------------------------------------------------------------------- == There are 3 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 4, 2011) is 4709 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Sheng 3 Internet-Draft F. Arias 4 Intended status: Informational ICANN 5 Expires: December 6, 2011 June 4, 2011 7 A RESTful Web Service for Domain Name Registration Data (RWS-DNRD) 8 draft-sheng-weirds-icann-rws-dnrd-00 10 Abstract 12 This document describes a pilot RESTful Web Service for querying 13 Domain Name Registration Data (aka WHOIS data). 15 The purpose of this document is to facilitate discussion and serve as 16 input into a standards process in this area, currently being 17 discussed on the WHOIS-based Extensible Internet Registration Data 18 Service (WEIRDS) mailing list 19 (https://www.ietf.org/mailman/listinfo/weirds). 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 6, 2011. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Domain Name Registration Data . . . . . . . . . . . . . . 3 57 1.2. REST and RESTful Web Service . . . . . . . . . . . . . . . 3 58 1.3. Why RESTful? . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Implmentation Description . . . . . . . . . . . . . . . . . . 5 61 3.1. The Request . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.2. The Response . . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 5. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . . 9 65 5.1. Contact XML Schema . . . . . . . . . . . . . . . . . . . . 11 66 5.2. Domain Name XML Schema . . . . . . . . . . . . . . . . . . 12 67 5.3. Host XML Schema . . . . . . . . . . . . . . . . . . . . . 14 68 5.4. RWS XML Schema . . . . . . . . . . . . . . . . . . . . . . 15 69 6. Internationalization Considerations . . . . . . . . . . . . . 16 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 71 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 72 8.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 16 73 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 74 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 10.1. Normative References . . . . . . . . . . . . . . . . . . . 16 76 10.2. Informative References . . . . . . . . . . . . . . . . . . 17 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 79 1. Introduction 81 This document describes a pilot implemention by ICANN staff for 82 querying domain name registration data through a RESTful Web-based 83 Interface. The service is implemented using the HTTP protocol 84 [RFC2616] and conforms to the architectural constraints of REST 85 [REST]. 87 1.1. Domain Name Registration Data 89 Domain Name Registration Data are data that a registrant provides 90 when s/he acquires or is assigned a domain name. By contract with 91 the Internet Corporation for Assigned Names and Numbers (hereinafter 92 ICANN), domain name system registries - domain registries and 93 registrars as defined by [RFC3707] - are to provide public access to 94 some of these data both via the WHOIS protocol ([RFC3912]) as well as 95 via a web interface. 97 1.2. REST and RESTful Web Service 99 REST stands for Representational State Transfer. It is a set of 100 architectural constraints that is developed as an abstract model of 101 the Web architecture. These constraints include: client-server 102 model, stateless, cacheable, layered system, code on demand 103 (optional), and uniform interface. REST was used to guide the 104 redesign of the Hypertext Transfer Protocol (HTTP) and Uniform 105 Resource Identifiers. It is widely regarded as the architecture of 106 the Web today. Principles of REST have been used to design other 107 protocols such as the ATOM publishing protocol. 109 A RESTful web service is a web service implemented using HTTP and the 110 principles of REST. It is a collection of resources, with three 111 defined aspects: 1) The "verbs" of the service are strictly those 112 defined by the HTTP methods GET, PUT, POST, and DELETE, 2) The 113 "verbs" are used to act upon resources, and 3) resources are 114 addressable using URLs. 116 1.3. Why RESTful? 118 Compared to the WHOIS protocol as defined in RFC 3912, we felt the 119 RESTful approach offers the following advantages: 121 Standardized output and error format: The base response output 122 format is XML, which when paired with a well-defined schema would 123 allow for automated processing. 125 Support for internationalisation: RWS has complete support for 126 internationalised registration data, as well as IDNs with 127 U-labels, by using the XML data format, which uses Unicode. 129 Authentication and access control: HTTP, the transport for RWS, 130 already supports authentication, and by means of using these 131 capabilities, RWS makes technically possible to implement granular 132 permissions over registration data if required. 134 Addressable Whois Service: RWS requires the use of a URI/URL 135 standard structure for each object/resource. This has the 136 additional benefit of providing a widely recognized manner to 137 refer unambiguously to objects in Whois. 139 Increased Usability: Some of the inherent capabilities of the HTTP 140 protocol (such as redirects) can be used to provide additional 141 functionality such as automatic referrals to more specific WHOIS 142 data sources without requiring specialized parsing by the client. 144 Authenticity of Origin: RWS provided over HTTPS offers confidence 145 in the origin of the information. 147 Leverage existing infrastructure and expertise: RWS is HTTP-based 148 and can be supported using popular web server infrastructures. 149 Web administration is a skill-set and resource likely already 150 commonplace inside registries and registrars. Similarly, RWS can 151 benefit from existing technology to implement load-balance 152 servers, cache answers to minimize network traffic, etc. 154 2. Terminology 156 For convenience, this implementation can be referred to as the 157 "RESTful Web Service for Domain Name Registration Data" or "RWS - 158 DNRD". The following terminology is used by this specification: 160 Domain Name Registration Data (aka WHOIS data) - refers to the 161 data that registrants provide when registering a domain name. 162 Part of these data are sometimes contractually required to be made 163 publicly available, these includes the name of the registrant, 164 name servers, the expiration date of the registration, etc. (see 165 section 3.3 section of Registrar Accreditation Agreement). 167 URI - A Uniform Resource Identifier as defined in [RFC3986]. 169 IRI - An internationalized Resource Identifier as defined in 170 [RFC3987]. 172 Resource - A network-accessible data object or service identified 173 by an URI, as defined in [RFC2616]. In this context, resources 174 refers to the registration data objects. 176 Representation - An entity included with a request or response as 177 defined in [RFC2616]. 179 3. Implmentation Description 181 ICANN's RWS-DNRD specifies the URL structure, the methods to be used, 182 the responses and its format, and the result codes. 184 As its name implies RWS-DNRD is Web-based, i.e., uses HTTP [RFC2616] 185 as its transport. Given its RESTful nature it only uses the standard 186 HTTP methods. And given it is read-only, it only usea the GET and 187 HEAD methods. 189 3.1. The Request 191 The server accepts standard HTTP "GET" requests for the resources it 192 serves. The client sends its request with the following URI 193 structure. 195 3.1.1. URL structure 197 Meta Data - URL: / Display information about resources, URI scheme 198 and allowed operations 200 Domain Name Request - /domain// example: 201 http://whois.test/domain/example.test/ 203 Contact Request - /contact// example: 204 http://whois.test/conact/CID-4005/ 206 Host Request - /host// example: 207 http://whois.test/host/ns1.example.test/ 209 3.2. The Response 211 The RWS-RDNRD server provide responses in XML format as specified 212 below and can offer responses in other formats; currently only HTML 213 and plain text. The client signals the preferred format using the 214 standard HTTP "Accept:" header. The client can also signal the 215 preferred format by adding a DOS-file-style extension to the 216 resource. For example, "/xreg/rsrc1.xml". If the client specifies 217 no preferred format, the server responds in XML. If the client 218 signals one format with the HTTP "Accept:" header and another with 219 the extension style, the server ignores the preference signaled with 220 the former. 222 The pilot implementation currently support the following values for 223 the Accept header: application/xml for XML, text/html for HTML, and 224 text/plain for plain text. 226 The root element for a RWS-DNRD response is . This element 227 contains one or more elements that are explained in the 228 following section. 230 Example of root element object: 232 233 236 ... 237 239 240 ... 241 242 ... 243 245 3.2.1. Response for Domain Names 247 Example Query: http://whois.test/domain/example.test/ 249 Response: 251 252 254 255 257 example.test 258 9690-TEST 259 260 261 263 4447 264 4447 265 4447 266 267 268 ns1.example.test 269 270 271 ns2.example.test 272 273 274 ns3.example.test 275 276 277 793 278 XYZ Corporation 279 1289 280 1992-07-26T09:10:56Z 282 2019-01-21T10:11:18Z 283 284 285 287 3.2.2. Response for Contacts 289 Example Query: http://whois.test/conact/4447/ 291 Response: 293 294 296 297 299 4447 300 4447-TEST 301 302 303 305 307 Nova D Janes 308 309 1755 XYZ Avenue 310 ABC 311 PA 312 15206 313 US 314 315 316 +1.1234567890 317 +1.1234567890 318 Nova.D.Janes@xyz.com 319 1289 320 1289 321 1995-11-29T03:17:09Z 322 1997-02-10T21:56:43Z 323 324 325 327 3.2.2.1. Response for Host Names 329 Example Query: http://whois.test/host/ns1.example.test/ 331 Response: 333 334 336 337 338 ns1.example.test 339 8998-TEST 340 341 342 344 188.17.219.3 345 1289 346 1289 347 1995-01-12T01:26:27Z 348 1289 349 2005-03-01T08:43:11Z 351 352 353 355 4. Error Codes 357 In compliance with the REST paradigm any error information is 358 returned in the form of a standard HTTP response with an HTTP status 359 code describing the error and a text/plain body message describing 360 the exception causing the error response. In this version we are 361 using only standard HTTP codes 362 (http://www.iana.org/assignments/http-status-codes). 364 We plan to define specialized error codes in the future. 366 5. Formal XML Syntax 368 The formal syntax presented here is a complete schema representation 369 suitable for automated validation of an XML instance. We base our 370 implementation on the Extension Provisioning Protocol (EPP). We 371 reference and include the following EPP schemas: 373 [RFC5730] - Extensible Provisioning Protocol (EPP) 375 [RFC5731] - Extensible Provisioning Protocol (EPP) Domain Name 376 Mapping 378 [RFC5732] - Extensible Provisioning Protocol (EPP) Host Mapping 380 [RFC5733] - Extensible Provisioning Protocol (EPP) Contact Mapping 382 5.1. Contact XML Schema 384 387 390 391 392 394 395 396 RESTful Whois schema for contact. 397 398 400 403 404 405 406 407 408 410 411 412 413 414 415 416 417 418 419 420 421 423 426 428 5.2. Domain Name XML Schema 430 433 436 437 438 439 441 442 443 RESTful Whois schema for domains 444 445 447 450 451 452 453 454 455 457 459 461 462 464 465 466 467 468 469 470 471 472 475 476 478 479 480 481 482 483 484 486 487 488 489 490 491 492 493 495 496 497 499 501 502 504 505 506 507 508 509 510 512 515 517 5.3. Host XML Schema 519 522 525 526 527 529 530 531 RESTful Whois schema for hosts 532 533 535 538 539 540 541 542 543 545 546 547 548 549 550 551 552 553 555 558 560 5.4. RWS XML Schema 561 564 567 568 569 570 572 573 574 RESTful Whois schema 575 576 578 581 582 584 587 588 589 591 592 594 595 596 597 598 599 600 601 603 606 607 608 610 611 613 616 618 6. Internationalization Considerations 620 Information published in RWS is represented in XML, which provides 621 native support for encoding information using the Unicode character 622 set and its more compact representations including UTF-8. Conformant 623 XML processors recognize both UTF-8 and UTF-16. Though XML includes 624 provisions to identify and use other character encodings through use 625 of an "encoding" attribute in an declaration, use of UTF-8 is 626 preferred. 628 7. IANA Considerations 630 TBD 632 8. Security Considerations 634 8.1. URIs and IRIs 636 RWS-DNRD implementations use URIs and IRIs. See Section 7 of 637 [RFC3986] and Section 8 of [RFC3987] for security considerations 638 related to their handling and use. 640 9. Acknowledgments 642 The authors would like to acknowledge the following individuals for 643 their input: Andrew Sullivan, and Dave Piscitello. 645 10. References 647 10.1. Normative References 649 [REST] Fielding, R. and R. Taylor, "Principled Design of the 650 Modern Web Architecture", ACM Transactions on Internet 651 Technology Vol. 2, No. 2, May 2002. 653 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 654 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 655 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 657 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 658 Resource Identifier (URI): Generic Syntax", STD 66, 659 RFC 3986, January 2005. 661 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 662 Identifiers (IRIs)", RFC 3987, January 2005. 664 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 665 STD 69, RFC 5730, August 2009. 667 [RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 668 Domain Name Mapping", STD 69, RFC 5731, August 2009. 670 [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 671 Host Mapping", STD 69, RFC 5732, August 2009. 673 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 674 Contact Mapping", STD 69, RFC 5733, August 2009. 676 10.2. Informative References 678 [RFC3707] Newton, A., "Cross Registry Internet Service Protocol 679 (CRISP) Requirements", RFC 3707, February 2004. 681 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 682 September 2004. 684 Authors' Addresses 686 Steve Sheng 687 Internet Corporation for Assigned Names and Numbers 688 4676 Admiralty Way, Suite 330 689 Marina del Rey 90292 690 United States of America 692 Phone: +1.310.823.9358 693 Email: steve.sheng@icann.org 694 Francisco Arias 695 Internet Corporation for Assigned Names and Numbers 696 4676 Admiralty Way, Suite 330 697 Marina del Rey 90292 698 United States of America 700 Phone: +1.310.823.9358 701 Email: francisco.arias@icann.org