idnits 2.17.1 draft-ietf-weirds-using-http-03.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: ' Security considerations: n/a' ) -- 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 (March 27, 2013) is 4047 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: September 28, 2013 APNIC 6 N. Kong 7 CNNIC 8 March 27, 2013 10 Using the Registration Data Access Protocol (RDAP) with HTTP 11 draft-ietf-weirds-using-http-03 13 Abstract 15 This document describes the usage of the Registration Data Access 16 Protocol (RDAP) using HTTP. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 28, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 1. Introduction 52 This document describes the usage of HTTP for Registration Data 53 Directory Services running on RESTful web servers. The goal of this 54 document is to tie together the usage patterns of HTTP into a common 55 profile applicable to the various types of Directory Services serving 56 Registration Data using RESTful styling. By giving the various 57 Directory Services common behavior, a single client is better able to 58 retrieve data from Directory Services adhering to this behavior. 60 In designing these common usage patterns, this draft endeavours to 61 satisfy requirements for a Registration Data Access Protocol (RDAP). 62 This draft also introduces an additional design consideration to 63 define a simple use of HTTP. Where complexity may reside, it is the 64 goal of this specification to place it upon the server and to keep 65 the client as simple as possible. A client implementation should be 66 possible using common operating system scripting tools. 68 This is the basic usage pattern for this protocol: 70 1. A client issues an HTTP query using GET. As an example, a query 71 for the network registration 192.0.2.0 might be http:// 72 example.com/ip/192.0.2.0. 74 2. If the receiving server has the information for the query, it 75 examines the Accept header field of the query and returns a 200 76 response with a response entity appropriate for the requested 77 format. 79 3. If the receiving server does not have the information for the 80 query but does have knowledge of where the information can be 81 found, it will return a redirection response (3xx) with the 82 Location: header containing an HTTP URL pointing to the 83 information or another server known to have knowledge of the 84 location of the information. The client is expected to re-query 85 using that HTTP URL. 87 4. If the receiving server does not have the information being 88 requested and does not have knowledge of where the information 89 can be found, it should return a 404 response. 91 It is important to note that it is not the intent of this document to 92 redefine the meaning and semantics of HTTP. The purpose of this 93 document is to clarify the use of standard HTTP mechanisms for this 94 application. 96 2. Terminology 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in RFC 2119 [RFC2119]. 101 As is noted in SSAC Report on WHOIS Terminology and Structure 102 [SAC-051], the term "Whois" is overloaded, often referring to a 103 protocol, a service and data. In accordance with [SAC-051], this 104 document describes the base behavior for a Registration Data Access 105 Protocol (RDAP). [SAC-051] describes a protocol profile of RDAP for 106 Domain Name Registries (DNRs), DNRD-AP. This document and others 107 from the IETF WEIRDS working group describe a single protocol, RDAP, 108 for access to the data of both DNRs and Regional Internet Registries 109 (RIRs). RIRs are also often referred to as number resource 110 registries and are responsible for the registration of IP address 111 networks and autonomous system numbers. 113 3. Design Intents 115 There are a few design criteria this document attempts to support. 117 First, each query is meant to return either zero or one result. With 118 the maximum upper bound being set to one, the issuance of redirects 119 is simplified to the known query/response model used by HTTP 120 [RFC2616]. Should a result contain more than one result, some of 121 which are better served by other servers, the redirection model 122 becomes much more complicated. 124 Second, multiple response formats are supported by this protocol. At 125 present the IETF WEIRDS working group is defining only a JSON 126 [RFC4627] response format, but server operators may use other data 127 formats when those formats are requested. 129 Third, HTTP offers a number of transport protocol mechanisms not 130 described further in this document. Operators are able to make use 131 of these mechanisms according to their local policy, including cache 132 control, authorization, compression, and redirection. HTTP also 133 benefits from widespread investment in scalability, reliability, and 134 performance, and widespread programmer understanding of client 135 behaviours for RESTful web services, reducing the cost to deploy 136 Registration Data Directory Services and clients. 138 4. Queries 139 4.1. Accept Header 141 RDAP clients MUST include an Accept: header specifying application/ 142 rdap+json, application/json, or both. Servers receiving an RDAP 143 request MUST return an entity with Content-Type application/ 144 rdap+json. 146 This specification does not define the responses a server returns to 147 a request with any other media types in the Accept: header, or with 148 no Accept: header. One possibility would be to return a response in 149 a media type suitable for rendering in a web browser. 151 4.2. Query Parameters 153 Servers SHOULD ignore unknown query parameters. Use of unknown query 154 parameters for cache-busting is described in Appendix A. 156 5. Types of HTTP Response 158 This section describes the various types of responses a server may 159 send to a client. While no standard HTTP response code is forbidden 160 in usage, at a minimum clients SHOULD understand the response codes 161 described in this section. It is expected that usage of response 162 codes and types for this application not defined here will be 163 described in subsequent documents. 165 5.1. Positive Answers 167 If a server has the information requested by the client and wishes to 168 respond to the client with the information according to its policies, 169 it SHOULD encode the answer in the format most appropriate according 170 to the standard and defined rules for processing the HTTP Accept 171 header, and return that answer in the body of a 200 response. 173 5.2. Redirects 175 If a server wishes to inform a client that the answer to a given 176 query can be found elsewhere, it SHOULD return either a 301 or a 307 177 response code and an HTTP URL in the Location: header. The client is 178 expected to issue a subsequent query using the given URL without any 179 processing of the URL. In other words, the server is to hand back a 180 complete URL and the client should not have to transform the URL to 181 follow it. 183 A server SHOULD use a 301 response to inform the client of a 184 permanent move and a 307 response otherwise. For this application, 185 such an example of a permanent move might be a top level domain (TLD) 186 operator informing a client the information being sought can be found 187 with another TLD operator (i.e. a query for the domain bar in 188 foo.example is found at http://foo.example/domain/bar). 190 In other words, when generating the redirect url, the server will 191 only alter the base of the URL. It will not attempt to normalize or 192 modify the path segment. 194 For example, if the client sends http://serv1.example.com/weirds/ 195 domain/example.com, the server redirecting to https:// 196 serv2.example.net/weirds2/ would set the Location: field to the 197 value: https://serv2.example.net/weirds2/domain/example.com. 199 5.3. Negative Answers 201 If a server wishes to respond that it has no information regarding 202 the query, it SHOULD return a 404 response code. Optionally, it MAY 203 include additional information regarding the negative answer in the 204 HTTP entity body. 206 5.4. Malformed Queries 208 If a server receives a query which it cannot understand, it SHOULD 209 return a 400 response code. Optionally, it MAY include additional 210 information regarding this negative answer in the HTTP entity body. 212 5.5. Rate Limits 214 Some servers apply rate limits to deter address scraping and other 215 abuses. When a server declines to answer a query due to rate limits, 216 it MAY return a 429 response code as described in [RFC6585]. A 217 client that receives a 429 response SHOULD decrease its query rate, 218 and honor the Retry-After header if one is present. 220 Note that this is not a defense against denial-of-service attacks, 221 since a malicious client could ignore the code and continue to send 222 queries at a high rate. 224 5.6. Cross-Origin Resource Sharing 226 When responding to queries, it is RECOMMENDED that servers use the 227 Access-Control-Allow-Origin header, as specified by 228 [W3C.WD-cors-20130129]. 230 6. Extensibility 232 For extensibility purposes, this document defines an IANA registry 233 for prefixes used in JSON [RFC4627] data serialization and URI path 234 segments (see Section 7). 236 Prefixes and identifiers SHOULD only consist of the alphabetic ASCII 237 characters A through Z in both uppercase and lowercase, the numerical 238 digits 0 through 9, underscore characters, and SHOULD NOT begin with 239 an underscore character, numerical digit or the characters "xml". 240 The following describes the production of JSON names in ABNF 241 [RFC5234]. 243 ABNF for JSON names 245 name = ALPHA *( ALPHA / DIGIT / "_" ) 247 Figure 1 249 This restriction is a union of the Ruby programming language 250 identifier syntax and the XML element name syntax and has two 251 purposes. First, client implementers using modern programming 252 languages such as Ruby or Java may use libraries that automatically 253 promote JSON names to first order object attributes or members. 254 Second, a clean mapping between JSON and XML is easy to accomplish 255 using these rules. 257 7. IANA Considerations 259 7.1. RDAP Extensions Registry 261 This specification proposes an IANA registry for RDAP extensions. 262 The purpose of this registry is to ensure uniqueness of extension 263 identifiers. The extension identifier is used as prefix in JSON 264 names and as a prefix of path segments in RDAP URLs. 266 The production rule for these identifiers is specified in Section 6. 268 In accordance with RFC5226, the IANA policy for assigning new values 269 shall be Specification Required: values and their meanings must be 270 documented in an RFC or in some other permanent and readily available 271 reference, in sufficient detail that interoperability between 272 independent implementations is possible. 274 The following is a preliminary template for an RDAP extension 275 registration: 277 Extension identifier: the identifier of the extension 279 Registry operator: the name of the registry operator 281 Published specification: RFC number, bibliographical reference or 282 URL to a permanent and readily available specification 284 Person & email address to contact for further information: The 285 names and email addresses of individuals for contact regarding 286 this registry entry 288 Intended usage: brief reasons for this registry entry 290 The following is an example of a registration in the RDAP extension 291 registry: 293 Extension identifier: lunarNic 295 Registry operator: The Registry of the Moon, LLC 297 Published specification: http://www.example/moon_apis/rdap 299 Person & email address to contact for further information: 300 Professor Bernardo de la Paz 302 Intended usage: COMMON 304 7.2. RDAP Media Type Registration 306 This specification registers the "application/rdap+json" media type. 308 Type name: application 310 Subtype name: rdap+json 312 Required parameters: n/a 314 Encoding considerations: n/a 316 Security considerations: n/a 318 Interoperability considerations: n/a 320 Published specification: [[ this document ]] 322 Applications that use this media type: RDAP 324 Additional information: n/a 325 Person & email address to contact for further information: Andy 326 Newton &andy@hxr.us& 328 Intended usage: COMMON 330 Restrictions on usage: none 332 Author: Andy Newton 334 Change controller: IETF 336 Provisional Registration: Yes 338 8. Internationalization Considerations 340 8.1. URIs and IRIs 342 Clients MAY use IRIs as they see fit, but MUST transform them to URIs 343 [RFC3986] for interaction with RDAP servers. RDAP servers MUST use 344 URIs in all responses, and clients MAY transform these URIs to IRIs. 346 8.2. Language Identifiers in Queries and Responses 348 Depending on the data format of the response, servers MAY include 349 data in character sets other than ASCII and languages other than 350 English (the data format will most likely be in Unicode and almost 351 certainly languages other than English will be encountered). Under 352 most scenarios, clients requesting data will not signal that the data 353 be returned in a particular language or script. On the other hand, 354 when servers return data and have knowledge that the data is in a 355 language or script, the data should be annotated with language 356 identifiers thus allowing clients to process and display the data 357 accordingly. 359 8.3. Language Identifiers in HTTP Headers 361 Given the description of the use of language identifiers in 362 Section 8.2, unless otherwise specified servers SHOULD ignore the 363 HTTP [RFC2616] Accept-Language header when formulating responses. 365 However, servers MAY return language identifiers in the Content- 366 Language header so as to inform clients of the intended language of 367 HTTP layer messages. 369 9. Contributing Authors and Acknowledgements 371 John Levine provided text to tighten up the Accept header usage and 372 the text for the section on 429 responses. 374 Marc Blanchet provided some clarifying text regarding the use of URLs 375 with redirects. 377 10. Normative References 379 [SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS 380 Terminology and Structure", September 2011. 382 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 383 Requirement Levels", BCP 14, RFC 2119, March 1997. 385 [RFC4627] Crockford, D., "The application/json Media Type for 386 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 388 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 389 Resource Identifier (URI): Generic Syntax", STD 66, RFC 390 3986, January 2005. 392 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 393 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 394 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 396 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 397 Specifications: ABNF", STD 68, RFC 5234, January 2008. 399 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 400 Codes", RFC 6585, April 2012. 402 [W3C.WD-cors-20130129] 403 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 404 Web Consortium LastCall WD-cors-20130129, January 2013, 405 . 407 Appendix A. Cache Busting 409 To overcome issues with misbehaving HTTP [RFC2616] cache 410 infrastructure, clients MAY use an adhoc and improbably used query 411 parameter with a random value of their choosing. As Section 4.2 412 instructs servers to ignore unknown parameters, this is unlikely to 413 have any known side effects. 415 An example of using an unknown query parameter to bust caches: 417 http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123 419 Use of an unknown parameter to overcome misbehaving caches is not 420 part of any specification and is offered here for informational 421 purposes. 423 Appendix B. Changelog 425 Initial WG -00: Updated to working group document 2012-September-20 427 -01 429 * Updated for the sections moved to the JSON responses draft. 431 * Simplified media type, removed "level" parameter. 433 * Updated 2119 language and added boilerplate. 435 * In section 1, noted that redirects can go to redirect servers 436 as well. 438 * Added Section 8.2 and Section 8.3. 440 -02 442 * Added a section on 429 response codes. 444 * Changed Accept header language in section 4.1 446 * Removed reference to the now dead requirements draft. 448 * Added contributing authors and acknowledgements section. 450 * Added some clarifying text regarding complete URLs in the 451 redirect section. 453 * Changed media type to application/rdap+json 455 * Added media type registration 457 -03 459 * Removed forward reference to draft-ietf-weirds-json-response. 461 * Added reference and recommended usage of CORS 463 Authors' Addresses 464 Andrew Lee Newton 465 American Registry for Internet Numbers 466 3635 Concorde Parkway 467 Chantilly, VA 20151 468 US 470 Email: andy@arin.net 471 URI: http://www.arin.net 473 Byron J. Ellacott 474 Asia Pacific Network Information Center 475 6 Cordelia Street 476 South Brisbane QLD 4101 477 Australia 479 Email: bje@apnic.net 480 URI: http://www.apnic.net 482 Ning Kong 483 China Internet Network Information Center 484 4 South 4th Street, Zhongguancun, Haidian District 485 Beijing 100190 486 China 488 Phone: +86 10 5881 3147 489 Email: nkong@cnnic.cn