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