idnits 2.17.1 draft-designteam-weirds-using-http-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. (A line matching the expected section header was found, but with an unexpected indentation: ' 5. Security considerations?' ) ** 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.) (A line matching the expected section header was found, but with an unexpected indentation: ' 4. IANA considerations' ) == There are 1 instance of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? ** 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 187: '... Clients SHOULD put the MIME type of...' RFC 2119 keyword, line 188: '...header. Servers SHOULD respond with a...' RFC 2119 keyword, line 191: '... the Accept header is NOT RECOMMENDED....' RFC 2119 keyword, line 194: '...nse, but servers MUST respond with the...' RFC 2119 keyword, line 197: '...AH version 1 in JSON. The server MUST...' (21 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 10, 2012) is 4340 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: 'RFC4034' is defined on line 462, but no explicit reference was found in the text == Unused Reference: 'RFC5396' is defined on line 477, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'SAC-051' ** 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 (~~), 4 warnings (==), 3 comments (--). 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: November 11, 2012 RIPE NCC 6 A. Servin 7 LACNIC 8 B. Ellacott 9 APNIC 10 S. Hollenbeck 11 Verisign 12 S. Sheng 13 F. Arias 14 ICANN 15 N. Kong 16 CNNIC 17 F. Obispo 18 ISC 19 May 10, 2012 21 Using HTTP for RESTful Whois Services by Internet Registries 22 draft-designteam-weirds-using-http-00 24 Abstract 26 This document describes the use of HTTP in Whois services using 27 RESTful web methodologies. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on November 11, 2012. 46 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. Design Intents . . . . . . . . . . . . . . . . . . . . . . . . 6 66 4. Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 4.1. Accept Header . . . . . . . . . . . . . . . . . . . . . . 7 68 4.2. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 7 69 5. Types of HTTP Response . . . . . . . . . . . . . . . . . . . . 8 70 5.1. Positive Answers . . . . . . . . . . . . . . . . . . . . . 8 71 5.2. Redirects . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5.3. Negative Answers . . . . . . . . . . . . . . . . . . . . . 8 73 5.4. Malformed Queries . . . . . . . . . . . . . . . . . . . . 8 74 6. Use of JSON . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 6.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 9 76 6.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 7. Use of XML . . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 7.1. Signaling . . . . . . . . . . . . . . . . . . . . . . . . 10 79 7.2. Naming and Structure . . . . . . . . . . . . . . . . . . . 10 80 8. Common Error Response Body . . . . . . . . . . . . . . . . . . 12 81 9. Common Datatypes . . . . . . . . . . . . . . . . . . . . . . . 13 82 10. Internationalization Considerations . . . . . . . . . . . . . 14 83 10.1. URIs vs IRIs . . . . . . . . . . . . . . . . . . . . . . . 14 84 10.2. Character Encoding . . . . . . . . . . . . . . . . . . . . 14 85 11. Normative References . . . . . . . . . . . . . . . . . . . . . 15 86 Appendix A. Areas of Improvement . . . . . . . . . . . . . . . . 16 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 89 1. Introduction 91 Over time, several deficiencies have been noted in the Whois protocol 92 as described in RFC 3912. The following is a partial list: 94 lack of standardized command structures 96 lack of standardized output and error structures 98 lack of support for internationalization (and therefore 99 localization) 101 lack of support for user identification, authentication, and 102 access control 104 This document describes the usage of HTTP for Internet registry Whois 105 services running on RESTful web servers for the purposes of 106 addressing the deficiencies as described above. The goal of this 107 document is to tie together the usage patterns of HTTP into a common 108 profile applicable to the various types of Internet registries 109 serving Whois data using RESTful styling. By giving the various 110 Internet registries a common behavior, a single client is better able 111 to retreive data from Internet registries adhering to this behavior. 113 The goal of this specification is to define a simple use of HTTP to 114 deliver Whois information using RESTful patterns. Where complexity 115 may reside, it is the goal of this specification to place it upon the 116 server and to keep the client as simple as possible. In the 117 vacubulary of computer programmers, it should be suffecient enough to 118 write a client for this application in bash using commands such as 119 wget or curl and other commonly available command line tools. 121 This is the basic usage pattern for this protocol: 123 1. A client issues an HTTP query using GET. As an example, a query 124 for the network registration 192.168.0.0 might be 125 http://example.com/ip/192.168.0.0. 127 2. If the receiving server has the information for the query, it 128 examines the Accept header of the query and returns a 200 129 response with a response entity appropriate for the requested 130 format. 132 3. If the receiving server does not have the information for the 133 query but does have knowledge of where the information can be 134 found, it will return a response of 301 or 303 with the Redirect 135 header containing an HTTP URL pointing to the information. The 136 client is expected to re-query using that HTTP URL. 138 4. If the receiving server does not have the information being 139 requested and does not have knowledge of where the information 140 can be found, it should return a 404 response. 142 It is important to note that it is not the intent of this document to 143 redefine the meaning and semantics of HTTP. The purpose of this 144 document is to clarify the use of standard HTTP mechanisms for this 145 application. 147 2. Terminology 149 As is noted in SSAC Report on WHOIS Terminology and Structure 150 [SAC-051], the term "Whois" is overloaded, often referring to a 151 protocol, a service and data. In accordance with [SAC-051], this 152 document describes the base behavior for a Registration Data Access 153 Protocol (RD-AP). At present, there are two known types of RD-AP, a 154 Domain Name Registration Data Access Protocol (DNRD-AP) and a Number 155 Resource Registration Data Access Protocol (NRRD-AP). Both the 156 DNRD-AP and NRRD-AP are to be built upon this base behavior, the 157 RD-AP. 159 Note that other types of RD-AP may exist in the future. 161 3. Design Intents 163 There are a few design criteria this document attempts to support. 165 First, each query is meant to return either zero or one result. With 166 the maximum upper bound being set to one, the issuance of redirects 167 is simplified to the known document model used by HTTP [RFC2616]. 168 Should a result contain more than one result, some of which are 169 better served by other servers, the redirection model becomes much 170 more complicated. 172 Second, multiple response formats are supported by this protocol. 173 This document outlines the base usage of JSON and XML, but server 174 operators may support other formats as they desire if appropriate. 176 Third, HTTP offers a number of transport protocol mechanisms not 177 described further in this document. Operators are able to make use 178 of these mechanisms according to their local policy, including cache 179 control, authorization, compression, and redirection. HTTP also 180 benefits from widespread investment in scalability, reliability, and 181 performance 183 4. Queries 185 4.1. Accept Header 187 Clients SHOULD put the MIME type of the format they desire in the 188 Accept header. Servers SHOULD respond with an appropriate MIME type 189 in the Accept header in accordance with the preference rules for the 190 Accept header in HTTP [RFC2616]. However the use by clients of 191 multiple MIME types in the Accept header is NOT RECOMMENDED. 193 Clients may use a generic MIME type for the desired data format of 194 the response, but servers MUST respond with the most appropriate MIME 195 type. In other words, a client may use "application\json" to express 196 that it desires JSON or "application\weirds_blah_v1+json" to express 197 that it desires WEIRDS BLAH version 1 in JSON. The server MUST 198 respond with "application\weirds_blah_v1+json". 200 4.2. Parameters 202 To overcome issues with misbehaving HTTP [RFC2616] cache 203 infrastructure, clients may use the '__weirds__cachebust' query 204 parameter with a random value of their choosing. Servers MUST ignore 205 this query parameter. 207 The following is an example use of this parameter to retreive the 208 abuse contacts associated with the most specific IP network with the 209 address 192.0.2.0: 211 /ip/192.0.2.0/operator/contacts/abuse?__weirds_cachebust=xyz123 213 For all others, servers SHOULD ignore unknown query parameters. 215 5. Types of HTTP Response 217 This section describes the various types of responses a server may 218 send to a client. While no standard HTTP response code is forbidden 219 in usage, at a minimum clients should understand the response codes 220 described in this section. It is expected that usage of response 221 codes and types for this application not defined here will be 222 described in subsequent documents. 224 5.1. Positive Answers 226 If a server has the information requested by the client and wishes to 227 respond to the client with the information according to its policies, 228 it should encode the answer in the format most appropriate according 229 to the standard and defined rules for processing the HTTP Accept 230 header, and return that answer in the body of a 200 response. 232 5.2. Redirects 234 If a server wishes to inform a client that the answer to a given 235 query can be found elsewhere, it should return either a 301 or a 303 236 reponse code and an HTTP URL in the Redirect header. The client is 237 expected to issue a subsequent query using the given URL without any 238 processing of the URL. In other words, the server is to hand back a 239 complete URL and the client should not have to transform the URL to 240 follow it. 242 A server should use a 301 response to inform the client of a 243 permanent move and a 303 repsonse otherwise. For this application, 244 such an example of a permentant move might be a TLD operator 245 informing a client the information being sought can be found with 246 another TLD operator (i.e. a query for the domain bar in foo.example 247 is found at http://foo.example/domain/bar). 249 5.3. Negative Answers 251 If a server wishes to respond that it has no information regarding 252 the query, it SHOULD return a 404 response code. Optionally, it may 253 include additional information regarding the lack of information as 254 defined by Section 8. 256 5.4. Malformed Queries 258 If a server receives a query which it cannot understand, it SHOULD 259 return a 503 response code. Optionally, it may include additional 260 information about why it does not understand the query as defined by 261 Section 8. 263 6. Use of JSON 265 6.1. Signaling 267 Clients may signal their desire for JSON using the "application\json" 268 mime type or a more application specific JSON mime type. 270 6.2. Naming 272 Clients processing JSON [RFC4627] responses SHOULD ignore values 273 associated with unrecognized names. Servers MAY insert values 274 signified by names into the JSON responses which are not specified in 275 this document. Insertion of unspecified values into JSON responses 276 SHOULD have names prefixed with a short identifier followed by an 277 underscore followed by a meaningful name. 279 For example, "handle" may be specified as the name of a value which 280 is a string containing a registry unique identifier for a 281 registration. The registry of the Moon might desire to insert a 282 value specific to their services denoting that a registration occured 283 before or after the first moon landing. The name for such a value 284 might take the form "lunarNic_beforeOneSmallStep". 286 JSON names SHOULD only consist of the alphabetic ASCII characters A 287 through Z in both uppercase and lowercase, underscore characters, and 288 SHOULD NOT begin with an underscore character or the characters 289 "xml". This restriction is a union of the Ruby programming language 290 identifier syntax and the XML element name syntax and has two 291 purposes. First, client implementers using modern programming 292 languages such as Ruby or Java may use libraries that automatically 293 promote JSON values to first order object attributes or members (e.g. 294 using the example above, the values may be referenced as 295 network.handle or network.lunarNic_beforeOneSmallStep). Second, a 296 clean mapping between JSON and XML is easy to accomplish using the 297 JSON representation. 299 Clients processing JSON responses MUST be prepared for values 300 specified in the registry response documents to be absent from a 301 response as no JSON value listed is required to appear in the 302 response. In other words, servers MAY remove values as is needed by 303 the policies of the server operator. 305 7. Use of XML 307 7.1. Signaling 309 Clients may signal their desire for XML using the "application\xml" 310 mime type or a more application specific XML mime type. 312 7.2. Naming and Structure 314 Well-formed XML may be programmatically produced using the JSON 315 encodings due to the JSON naming rules outlined in Section 6.2 and 316 the following simple rules: 318 1. Where a JSON name is given, the corresponding XML element has the 319 same name. 321 2. Where a JSON value is found, it is the content of the 322 corresponding XML element. 324 3. Where a JSON value is an array, the XML element is to be repeated 325 for each element of the array. 327 4. The root tag of the XML document is to be "response". 329 Consider the following JSON response. 331 { 332 "startAddress" : "10.0.0.0", 333 "endAddress" : "10.0.0.255", 334 "remarks" : [ 335 "she sells seas shells", 336 "down by the seashore" 337 ], 338 "uris" : [ 339 { 340 "type" : "source", 341 "uri" : "http://whois-rws.net/network/xxxx" 342 }, 343 { 344 "type" : "parent", 345 "uri" : "http://whois-rws.net/network/yyyy" 346 } 347 } 349 Figure 1 351 The corresponding XML would look like this: 353 354 10.0.0.0 355 10.0.0.255 356 She sells sea shells 357 down by the seashore 358 359 source 360 http://whois-rws.net/network/xxxx 361 362 363 parent 364 http://whois-rws.net/network/yyyy 365 366 368 The rules for clients processing XML responses are the same as those 369 with JSON: clients SHOULD ignore unrecognized XML elements, and 370 servers MAY insert XML elements with tag names according to the 371 naming rules in Section 6.2. And as with JSON, clients MUST be 372 prepared for XML elements specified in the registry response 373 documents to be absent from a response as no XML element listed is 374 required to appear in the response. 376 8. Common Error Response Body 378 As specified in Section 5, some non-answer responses may return 379 entity bodies with information that could be more descriptive. 381 The basic structure of that response is a data class containing an 382 error code number (corresponding to the HTTP response code) followed 383 by a string named "title" followed by an array of strings named 384 "description". 386 This is an example of the JSON version of the common response body. 388 { 389 "errorCode": 418 390 "title": "No More Tacos", 391 "description": [ 392 "We ran out of shells and sauce.", 393 "Come back tomorrow." ] 394 } 396 Figure 2 398 This is an example of the XML version of the common response body. 400 401 418 402 No More Tacos 403 We ran out of shells and sauce. 404 Come back tomorrow. 405 407 Figure 3 409 The MIME type for the JSON structure is 410 "application\weirds_common_error_v1+json" and the MIME type for the 411 XML document is "application\weirds_common_error_v1+xml". 413 A client MAY simply use the HTTP response code as the server is not 414 required to include error data in the response body. However, if a 415 client wishes to parse the error data, it SHOULD first check that the 416 Accept header contains the appropriate MIME type. 418 9. Common Datatypes 420 This section describes common data types found in Internet 421 registries. Unless otherwise stated by the response specification of 422 an Internet registry using this specification as a basis, the data 423 types can assume to be as follows: 425 1. IPv4 addresses - [RFC0791] 427 2. IPv6 addresses - [RFC5952] 429 3. country code - [ISO.3166.1988] 431 4. domain name - [RFC4343] 433 5. email address - [RFC5322] 435 6. date and time strings - [RFC3339] 437 10. Internationalization Considerations 439 10.1. URIs vs IRIs 441 Clients MAY use IRIs as they see fit, but MUST transform them to URIs 442 [RFC3986] for interaction with RD-AP servers. RD-AP servers MUST use 443 URIs in all responses, and clients MAY transform these URIs to IRIs. 445 10.2. Character Encoding 447 The default text encoding for JSON and XML responses in RD-AP is 448 UTF-8, and all servers and clients MUST support UTF-8. Servers and 449 clients MAY optionally support other character encodings. 451 11. Normative References 453 [SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS 454 Terminology and Structure", September 2011. 456 [RFC4627] Crockford, D., "The application/json Media Type for 457 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 459 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 460 Internet: Timestamps", RFC 3339, July 2002. 462 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 463 Rose, "Resource Records for the DNS Security Extensions", 464 RFC 4034, March 2005. 466 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 467 September 1981. 469 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 470 Address Text Representation", RFC 5952, August 2010. 472 [ISO.3166.1988] 473 International Organization for Standardization, "Codes for 474 the representation of names of countries, 3rd edition", 475 ISO Standard 3166, August 1988. 477 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 478 Autonomous System (AS) Numbers", RFC 5396, December 2008. 480 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 481 Clarification", RFC 4343, January 2006. 483 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 484 Resource Identifier (URI): Generic Syntax", STD 66, 485 RFC 3986, January 2005. 487 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 488 October 2008. 490 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 491 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 492 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 494 Appendix A. Areas of Improvement 496 Things that need to be done to this draft. 498 1. authentication what? 500 2. clean up must should, ref 2119? 502 3. better language on data formats... it was just a rough start 504 4. IANA considerations 506 5. Security considerations? 508 6. Is there a privacy considerations things we have to do now? 510 Authors' Addresses 512 Andrew Lee Newton 513 American Registry for Internet Numbers 514 3635 Concorde Parkway 515 Chantilly, VA 20151 516 US 518 Email: andy@arin.net 519 URI: http://www.arin.net 521 Kaveh Ranjbar 522 RIPE Network Coordination Centre 523 Singel 258 524 Amsterdam 1016AB 525 NL 527 Email: kranjbar@ripe.net 528 URI: http://www.ripe.net 530 Arturo L. Servin 531 Latin American and Caribbean Internet Address Registry 532 Rambla Republica de Mexico 6125 533 Montevideo 11300 534 UY 536 Email: aservin@lacnic.net 537 URI: http://www.lacnic.net 539 Byron J. Ellacott 540 Asia Pacific Network Information Center 541 6 Cordelia Street 542 South Brisbane QLD 4101 543 Australia 545 Email: bje@apnic.net 546 URI: http://www.apnic.net 547 Scott Hollenbeck 548 Verisign Labs 549 12061 Bluemont Way 550 Reston, VA 20190 551 US 553 Email: shollenbeck@verisign.com 554 URI: http://www.verisignlabs.com/ 556 Steve Sheng 557 Internet Corporation for Assigned Names and Numbers 558 4676 Admiralty Way, Suite 330 559 Marina del Rey, CA 90292 560 United States of America 562 Phone: +1.310.823.9358 563 Email: steve.sheng@icann.org 565 Francisco Arias 566 Internet Corporation for Assigned Names and Numbers 567 4676 Admiralty Way, Suite 330 568 Marina del Rey, CA 90292 569 United States of America 571 Phone: +1.310.823.9358 572 Email: francisco.arias@icann.org 574 Ning Kong 575 China Internet Network Information Center 576 4 South 4th Street, Zhongguancun, Haidian District 577 Beijing 100190 578 China 580 Phone: +86 10 5881 3147 581 Email: nkong@cnnic.cn 582 Francisco Obispo 583 Internet Systems Consortium 584 950 Charter St 585 Redwood City, CA 94063 586 United States of America 588 Phone: +1.650.423.1374 589 Email: fobispo@isc.org