idnits 2.17.1 draft-ietf-weirds-using-http-04.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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. -- 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? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 17, 2013) is 3998 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) -- 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: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A.L. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track B.J. Ellacott 5 Expires: October 17, 2013 APNIC 6 N. Kong 7 CNNIC 8 April 17, 2013 10 HTTP usage in the Registration Data Access Protocol (RDAP) 11 draft-ietf-weirds-using-http-04 13 Abstract 15 This document is one of a collection that together describe the 16 Registration Data Access Protocol (RDAP). It describes how RDAP is 17 transported using the Hypertext Transfer Protocol (HTTP). 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 October 17, 2013. 36 Copyright Notice 38 Copyright (c) 2013 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 (http://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 1. Introduction 51 This document describes the usage of HTTP for Registration Data 52 Directory Services. The goal of this document is to tie together 53 usage patterns of HTTP into a common profile applicable to the 54 various types of Directory Services serving Registration Data using 55 RESTful practices. By giving the various Directory Services common 56 behavior, a single client is better able to retrieve data from 57 Directory Services adhering to this behavior. 59 The registration data expected to be presented by this service is 60 Internet resource registration data - registration of domain names 61 and Internet number resources. This data is typically provided by 62 WHOIS [RFC3912] services, but the WHOIS protocol is insufficient to 63 modern registration data service requirements. A replacement 64 protocol is expected to retain the simple transactional nature of 65 WHOIS, while providing a specification for queries and responses, 66 redirection to authoritative sources, support for Internationalized 67 Domain Names (IDNs, [RFC5890]), and support for localized 68 registration data such as addresses and organisation or person names. 70 In designing these common usage patterns, this document introduces 71 considerations for a simple use of HTTP. Where complexity may 72 reside, it is the goal of this document to place it upon the server 73 and to keep the client as simple as possible. A client 74 implementation should be possible using common operating system 75 scripting tools. 77 This is the basic usage pattern for this protocol: 79 1. A client issues an HTTP query using GET. As an example, a query 80 for the network registration 192.0.2.0 might be http:// 81 example.com/ip/192.0.2.0. 83 2. If the receiving server has the information for the query, it 84 examines the Accept header field of the query and returns a 200 85 response with a response entity appropriate for the requested 86 format. 88 3. If the receiving server does not have the information for the 89 query but does have knowledge of where the information can be 90 found, it will return a redirection response (3xx) with the 91 Location: header field containing an HTTP(S) URL (Uniform 92 Resource Locator) pointing to the information or another server 93 known to have knowledge of the location of the information. The 94 client is expected to re-query using that HTTP URL. 96 4. If the receiving server does not have the information being 97 requested and does not have knowledge of where the information 98 can be found, it returns a 404 response. 100 5. If the receiving server will not answer a request for policy 101 reasons, it will return an error response (4xx) indicating the 102 reason for giving no answer. 104 It is important to note that it is not the intent of this document to 105 redefine the meaning and semantics of HTTP. The purpose of this 106 document is to clarify the use of standard HTTP mechanisms for this 107 application. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [RFC2119]. 115 As is noted in SSAC Report on WHOIS Terminology and Structure 116 [SAC-051], the term "WHOIS" is overloaded, often referring to a 117 protocol, a service and data. In accordance with [SAC-051], this 118 document describes the base behavior for a Registration Data Access 119 Protocol (RDAP). [SAC-051] describes a protocol profile of RDAP for 120 Domain Name Registries (DNRs), the Domain Name Registration Data 121 Access Protocol (DNRD-AP). 123 In this document, an RDAP client is an HTTP User Agent performing an 124 RDAP query, and an RDAP server is an HTTP server providing an RDAP 125 response. RDAP query and response formats are described in other 126 documents in the collection of RDAP specifications, while this 127 document describes how RDAP clients and servers use HTTP to exchange 128 queries and responses. 130 3. Design Intents 132 There are a few design criteria this document attempts to meet. 134 First, each query is meant to return either zero or one result. With 135 the maximum upper bound being set to one, the issuance of redirects 136 is simplified to the known query/response model used by HTTP 137 [RFC2616]. Should an entity contain more than one result, some of 138 which are better served by other servers, the redirection model 139 becomes much more complicated. 141 Second, multiple response formats are supported by this protocol. At 142 present the IETF WEIRDS working group is defining only a JSON 143 [RFC4627] response format, but server operators may use other data 144 formats when those formats are requested. 146 Third, this protocol is intended to be able to make use of the range 147 of mechanisms available for use with HTTP. HTTP offers a number of 148 mechanisms not described further in this document. Operators are 149 able to make use of these mechanisms according to their local policy, 150 including cache control, authorization, compression, and redirection. 151 HTTP also benefits from widespread investment in scalability, 152 reliability, and performance, and widespread programmer understanding 153 of client behaviours for RESTful web services, reducing the cost to 154 deploy Registration Data Directory Services and clients. 156 4. Queries 158 4.1. Accept Header 160 RDAP clients MUST include an Accept: header field specifying 161 application/rdap+json, application/json, or both. Servers receiving 162 an RDAP request MUST return an entity with Content-Type application/ 163 rdap+json. 165 This specification does not define the responses a server returns to 166 a request with any other media types in the Accept: header field, or 167 with no Accept: header field. One possibility would be to return a 168 response in a media type suitable for rendering in a web browser. 170 4.2. Query Parameters 172 Servers MUST ignore unknown query parameters. Use of unknown query 173 parameters for cache-busting is described in Appendix Appendix B. 175 5. Types of HTTP Response 177 This section describes the various types of responses a server may 178 send to a client. While no standard HTTP response code is forbidden 179 in usage, at a minimum clients SHOULD understand the response codes 180 described in this section. It is expected that usage of response 181 codes and types for this application not defined here will be 182 described in subsequent documents. 184 5.1. Positive Answers 186 If a server has the information requested by the client and wishes to 187 respond to the client with the information according to its policies, 188 it encodes the answer in the format most appropriate according to the 189 standard and defined rules for processing the HTTP Accept header 190 field, and return that answer in the body of a 200 response. 192 5.2. Redirects 194 If a server wishes to inform a client that the answer to a given 195 query can be found elsewhere, it MUST return a 301 response code to 196 indicate a permanent move, or a 307 response code to indicate a non- 197 permanent redirection, and include an HTTP(s) URL in the Location: 198 header field. The client is expected to issue a subsequent request 199 to satisfy the original query using the given URL without any 200 processing of the URL. In other words, the server is to hand back a 201 complete URL and the client should not have to transform the URL to 202 follow it. 204 For this application, such an example of a permanent move might be a 205 Top Level Domain (TLD) operator informing a client the information 206 being sought can be found with another TLD operator (i.e. a query 207 for the domain bar in foo.example is found at http://foo.example/ 208 domain/bar). 210 For example, if the client sends http://serv1.example.com/weirds/ 211 domain/example.com, the server redirecting to https:// 212 serv2.example.net/weirds2/ would set the Location: field to the 213 value: https://serv2.example.net/weirds2/domain/example.com. 215 5.3. Negative Answers 217 If a server wishes to respond that it has no information regarding 218 the query, it MUST return a 404 response code. Optionally, it MAY 219 include additional information regarding the negative answer in the 220 HTTP entity body. 222 If a server wishes to inform the client that information about the 223 query is available, but cannot include the information in the 224 response to the client for policy reasons, the server MUST respond 225 with an appropriate response code out of HTTP's 4xx range. Clients 226 MAY retry the query based on the respective response code. 228 5.4. Malformed Queries 230 If a server receives a query which it cannot interpret as an RDAP 231 query, it MUST return a 400 response code. Optionally, it MAY 232 include additional information regarding this negative answer in the 233 HTTP entity body. 235 5.5. Rate Limits 237 Some servers apply rate limits to deter address scraping and other 238 abuses. When a server declines to answer a query due to rate limits, 239 it SHOULD return a 429 response code as described in [RFC6585]. A 240 client that receives a 429 response SHOULD decrease its query rate, 241 and honor the Retry-After header field if one is present. 243 Note that this is not a defense against denial-of-service attacks, 244 since a malicious client could ignore the code and continue to send 245 queries at a high rate. A server might use another response code if 246 it did not wish to reveal to a client that rate limiting is the 247 reason for the denial of a reply. 249 5.6. Cross-Origin Resource Sharing 251 When responding to queries, it is RECOMMENDED that servers use the 252 Access-Control-Allow-Origin header field, as specified by [W3C.CR- 253 cors-20130129]. 255 6. Extensibility 257 For extensibility purposes, this document defines an IANA registry 258 for prefixes used in JSON [RFC4627] data serialization and URI path 259 segments (see Section 8). 261 Prefixes and identifiers SHOULD only consist of the alphabetic ASCII 262 characters A through Z in both uppercase and lowercase, the numerical 263 digits 0 through 9, underscore characters, and SHOULD NOT begin with 264 an underscore character, numerical digit or the characters "xml". 265 The following describes the production of JSON names in ABNF 266 [RFC5234]. 268 ABNF for JSON names 270 name = ALPHA *( ALPHA / DIGIT / "_" ) 272 This restriction is a union of the Ruby programming language 273 identifier syntax and the XML element name syntax and has two 274 purposes. First, client implementers using modern programming 275 languages such as Ruby or Java can use libraries that automatically 276 promote JSON names to first order object attributes or members. 277 Second, a clean mapping between JSON and XML is easy to accomplish 278 using these rules. 280 7. Security Considerations 282 This document does not pose strong security requirements to the RDAP 283 protocol. However, it does not restrict against the use of security 284 mechanisms offered by the HTTP protocol. 286 This document made recommendations for server implementations against 287 denial-of-service (Section 5.5) and interoperability with existing 288 security mechanism in HTTP clients (Section 5.6). 290 Additional security considerations to the RDAP protocol will be 291 covered in future RFCs documenting specific security mechanisms and 292 schemes. 294 8. IANA Considerations 296 8.1. RDAP Extensions Registry 298 This specification proposes an IANA registry for RDAP extensions. 299 The purpose of this registry is to ensure uniqueness of extension 300 identifiers. The extension identifier is used as a prefix in JSON 301 names and as a prefix of path segments in RDAP URLs. 303 The production rule for these identifiers is specified in Section 6. 305 In accordance with RFC5226, the IANA policy for assigning new values 306 shall be Specification Required: values and their meanings must be 307 documented in an RFC or in some other permanent and readily available 308 reference, in sufficient detail that interoperability between 309 independent implementations is possible. 311 The following is a preliminary template for an RDAP extension 312 registration: 314 Extension identifier: the identifier of the extension 316 Registry operator: the name of the registry operator 318 Published specification: RFC number, bibliographical reference or 319 URL to a permanent and readily available specification 321 Person & email address to contact for further information: The 322 names and email addresses of individuals for contact regarding 323 this registry entry 325 Intended usage: brief reasons for this registry entry 327 The following is an example of a registration in the RDAP extension 328 registry: 330 Extension identifier: lunarNic 332 Registry operator: The Registry of the Moon, LLC 334 Published specification: http://www.example/moon_apis/rdap 336 Person & email address to contact for further information: 337 Professor Bernardo de la Paz 339 Intended usage: COMMON 341 8.2. RDAP Media Type Registration 343 This specification registers the "application/rdap+json" media type. 345 Type name: application 347 Subtype name: rdap+json 349 Required parameters: n/a 351 Encoding considerations: n/a 353 Security considerations: n/a 355 Interoperability considerations: n/a 357 Published specification: [[ this document ]] 359 Applications that use this media type: RDAP 361 Additional information: n/a 362 Person & email address to contact for further information: Andy 363 Newton 365 Intended usage: COMMON 367 Restrictions on usage: none 369 Author: Andy Newton 371 Change controller: IETF 373 Provisional Registration: Yes 375 9. Internationalization Considerations 377 9.1. URIs and IRIs 379 Clients MAY use IRIs [RFC3987] as they see fit, but MUST transform 380 them to URIs [RFC3986] for interaction with RDAP servers. RDAP 381 servers MUST use URIs in all responses, and clients MAY transform 382 these URIs to IRIs. 384 9.2. Language Identifiers in Queries and Responses 386 Under most scenarios, clients requesting data will not signal that 387 the data be returned in a particular language or script. On the 388 other hand, when servers return data and have knowledge that the data 389 is in a language or script, the data SHOULD be annotated with 390 language identifiers whenever they are available, thus allowing 391 clients to process and display the data accordingly. 393 The mechanism for including a language identifier in a response will 394 be defined in subsequent documents describing specific response 395 formats. 397 9.3. Language Identifiers in HTTP Headers 399 Given the description of the use of language identifiers in Section 400 9.2, unless otherwise specified servers SHOULD ignore the HTTP 401 [RFC2616] Accept-Language header field when formulating HTTP entity 402 responses, so that clients do not conflate the Accept-Language header 403 with the 'lang' values in the entity body. 405 However, servers MAY return language identifiers in the Content- 406 Language header field so as to inform clients of the intended 407 language of HTTP layer messages. 409 10. Contributing Authors and Acknowledgements 411 John Levine provided text to tighten up the Accept header field usage 412 and the text for the section on 429 responses. 414 Marc Blanchet provided some clarifying text regarding the use of URLs 415 with redirects, as well as very useful feedback during WGLC. 417 Normative language reviews were provided by Murray S. Kucherawy and 418 Andrew Sullivan. 420 Jean-Phillipe Dionne provided text for the Security Considerations 421 section. 423 11. References 425 [SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS 426 Terminology and Structure", September 2011. 428 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 429 Requirement Levels", BCP 14, RFC 2119, March 1997. 431 [RFC4627] Crockford, D., "The application/json Media Type for 432 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 434 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 435 September 2004. 437 [RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 438 Resource Identifier (URI): Generic Syntax", STD 66, RFC 439 3986, January 2005. 441 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 442 Identifiers (IRIs)", RFC 3987, January 2005. 444 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 445 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 446 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 448 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 449 Specifications: ABNF", STD 68, RFC 5234, January 2008. 451 [RFC5890] Klensin, J., "Internationalized Domain Names for 452 Applications (IDNA): Definitions and Document Framework", 453 RFC 5890, August 2010. 455 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 456 Codes", RFC 6585, April 2012. 458 [W3C.CR-cors-20130129] 459 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 460 Web Consortium Candidate Recommendation CR-cors-20130129, 461 January 2013, . 464 Appendix A. Protocol Example 465 To demonstrate typical behaviour of an RDAP client and server, the 466 following is an example of an exchange, including a redirect. The 467 data in the response has been elided for brevity, as the data format 468 is not described in this document. 470 An example of an RDAP client and server exchange: 472 Client: 473 474 GET /ip/203.0.113.0/24 HTTP/1.1 475 Host: rdap.example.com 476 Accept: application/rdap+json 478 rdap.example.com: 479 HTTP 301 Moved Permanently 480 Location: http://rdap-ip.example.com/ip/203.0.113.0/24 481 Content-Length: 0 482 Content-Type: application/rdap+json; charset=UTF-8 483 485 Client: 486 487 GET /ip/203.0.113.0/24 HTTP/1.1 488 Host: rdap-ip.example.com 489 Accept: application/rdap+json 491 rdap-ip.example.com: 492 HTTP 200 OK 493 Content-Type: application/rdap_json; charset=UTF-8 494 Content-Length: 9001 496 { ... } 497 499 Appendix B. Cache Busting 501 Some HTTP [RFC2616] cache infrastructure does not adhere to caching 502 standards adequately, and could cache responses longer than is 503 intended by the server. To overcome these issues, clients MAY use an 504 adhoc and improbably used query parameter with a random value of 505 their choosing. As Section 4.2 instructs servers to ignore unknown 506 parameters, this is unlikely to have any known side effects. 508 An example of using an unknown query parameter to bust caches: 510 http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123 512 Use of an unknown parameter to overcome misbehaving caches is not 513 part of any specification and is offered here for informational 514 purposes. 516 Appendix C. Changelog 518 Initial WG -00: Updated to working group document 2012-September-20 520 -01 522 * Updated for the sections moved to the JSON responses draft. 524 * Simplified media type, removed "level" parameter. 526 * Updated 2119 language and added boilerplate. 528 * In section 1, noted that redirects can go to redirect servers 529 as well. 531 * Added Section 9.2 and Section 9.3. 533 -02 535 * Added a section on 429 response codes. 537 * Changed Accept header language in section 4.1 539 * Removed reference to the now dead requirements draft. 541 * Added contributing authors and acknowledgements section. 543 * Added some clarifying text regarding complete URLs in the 544 redirect section. 546 * Changed media type to application/rdap+json 548 * Added media type registration 550 -03 552 * Removed forward reference to draft-ietf-weirds-json-response. 554 * Added reference and recommended usage of CORS 556 -04 558 * Revised introduction and abstract. 560 * Added negative responses other than 404. 562 * Added security considerations. 564 * Added and corrected references: CORS, RFC3912, RFC3987, 565 RFC5890. 567 * Expanded on first use several acronyms. 569 * Updated 2119 language. 571 Authors' Addresses 573 Andrew Lee Newton 574 American Registry for Internet Numbers 575 3635 Concorde Parkway 576 Chantilly, VA 20151 577 US 579 Email: andy@arin.net 580 URI: http://www.arin.net 582 Byron J. Ellacott 583 Asia Pacific Network Information Center 584 6 Cordelia Street 585 South Brisbane QLD 4101 586 Australia 588 Email: bje@apnic.net 589 URI: http://www.apnic.net 591 Ning Kong 592 China Internet Network Information Center 593 4 South 4th Street, Zhongguancun, Haidian District 594 Beijing 100190 595 China 597 Phone: +86 10 5881 3147 598 Email: nkong@cnnic.cn