draft-ietf-weirds-using-http-08.txt   draft-ietf-weirds-using-http-09.txt 
Network Working Group A. Newton Network Working Group A. Newton
Internet-Draft ARIN Internet-Draft ARIN
Intended status: Standards Track B. Ellacott Intended status: Standards Track B. Ellacott
Expires: August 8, 2014 APNIC Expires: February 8, 2015 APNIC
N. Kong N. Kong
CNNIC CNNIC
February 4, 2014 August 7, 2014
HTTP usage in the Registration Data Access Protocol (RDAP) HTTP usage in the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-using-http-08 draft-ietf-weirds-using-http-09
Abstract Abstract
This document is one of a collection that together describe the This document is one of a collection that together describe the
Registration Data Access Protocol (RDAP). It describes how RDAP is Registration Data Access Protocol (RDAP). It describes how RDAP is
transported using the Hypertext Transfer Protocol (HTTP). transported using the Hypertext Transfer Protocol (HTTP).
Normative Reference Note
Normative references to RFC 7231 and draft-ietf-httpbis-http2 can be
replaced with a reference to RFC 2616 if draft-ietf-httpbis-http2 is
still a work in progress when this document is ready for publication.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 8, 2014. This Internet-Draft will expire on February 8, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 41 skipping to change at page 2, line 46
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
11.1. Normative References . . . . . . . . . . . . . . . . . . 10 11.1. Normative References . . . . . . . . . . . . . . . . . . 10
11.2. Informative References . . . . . . . . . . . . . . . . . 10 11.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 11 Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 11
Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 11 Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 11
Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 12 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
This document describes the usage of HTTP for Registration Data This document describes the usage of HTT[RFC7231]P for Registration
Directory Services. The goal of this document is to tie together Data Directory Services. The goal of this document is to tie
usage patterns of HTTP into a common profile applicable to the together usage patterns of HTTP into a common profile applicable to
various types of Directory Services serving Registration Data using the various types of Directory Services serving Registration Data
RESTful practices. By giving the various Directory Services common using RESTful practices. By giving the various Directory Services
behavior, a single client is better able to retrieve data from common behavior, a single client is better able to retrieve data from
Directory Services adhering to this behavior. Directory Services adhering to this behavior.
The registration data expected to be presented by this service is The registration data expected to be presented by this service is
Internet resource registration data - registration of domain names Internet resource registration data - registration of domain names
and Internet number resources. This data is typically provided by and Internet number resources. This data is typically provided by
WHOIS [RFC3912] services, but the WHOIS protocol is insufficient to WHOIS [RFC3912] services, but the WHOIS protocol is insufficient to
modern registration data service requirements. A replacement modern registration data service requirements. A replacement
protocol is expected to retain the simple transactional nature of protocol is expected to retain the simple transactional nature of
WHOIS, while providing a specification for queries and responses, WHOIS, while providing a specification for queries and responses,
redirection to authoritative sources, support for Internationalized redirection to authoritative sources, support for Internationalized
skipping to change at page 3, line 21 skipping to change at page 3, line 27
In designing these common usage patterns, this document introduces In designing these common usage patterns, this document introduces
considerations for a simple use of HTTP. Where complexity may considerations for a simple use of HTTP. Where complexity may
reside, it is the goal of this document to place it upon the server reside, it is the goal of this document to place it upon the server
and to keep the client as simple as possible. A client and to keep the client as simple as possible. A client
implementation should be possible using common operating system implementation should be possible using common operating system
scripting tools. scripting tools.
This is the basic usage pattern for this protocol: This is the basic usage pattern for this protocol:
1. A client issues an HTTP query using GET. As an example, a query 1. A client issues an HTTP query using GE[I-D.ietf-httpbis-http2]T.
for the network registration 192.0.2.0 might be http:// As an example, a query for the network registration 192.0.2.0
example.com/ip/192.0.2.0. might be http://example.com/ip/192.0.2.0.
2. If the receiving server has the information for the query, it 2. If the receiving server has the information for the query, it
examines the Accept header field of the query and returns a 200 examines the Accept header field of the query and returns a 200
response with a response entity appropriate for the requested response with a response entity appropriate for the requested
format. format.
3. If the receiving server does not have the information for the 3. If the receiving server does not have the information for the
query but does have knowledge of where the information can be query but does have knowledge of where the information can be
found, it will return a redirection response (3xx) with the found, it will return a redirection response (3xx) with the
Location: header field containing an HTTP(S) URL (Uniform Location: header field containing an HTTP(S) URL (Uniform
skipping to change at page 4, line 32 skipping to change at page 4, line 37
documents in the collection of RDAP specifications, while this documents in the collection of RDAP specifications, while this
document describes how RDAP clients and servers use HTTP to exchange document describes how RDAP clients and servers use HTTP to exchange
queries and responses. queries and responses.
3. Design Intents 3. Design Intents
There are a few design criteria this document attempts to meet. There are a few design criteria this document attempts to meet.
First, each query is meant to return either zero or one result. With First, each query is meant to return either zero or one result. With
the maximum upper bound being set to one, the issuance of redirects the maximum upper bound being set to one, the issuance of redirects
is simplified to the known query/response model used by HTTP is simplified to the traditional query/response model used by HTTP
[RFC2616]. Should an entity contain more than one result, some of [RFC7231]. Should an entity contain more than one result, some of
which are better served by other servers, the redirection model which are better served by other servers, the redirection model
becomes much more complicated. becomes much more complicated.
Second, the semantics of the request/response allow for future and/or Second, the semantics of the request/response allow for future and/or
non-standard response formats. In this document, only a JSON non-standard response formats. In this document, only a JSON
[RFC4627] response media type is noted, with the response contents to [RFC4627] response media type is noted, with the response contents to
be described separately. This document only describes how RDAP is be described separately. This document only describes how RDAP is
transported using HTTP with this format. transported using HTTP with this format.
Third, this protocol is intended to be able to make use of the range Third, this protocol is intended to be able to make use of the range
skipping to change at page 6, line 11 skipping to change at page 6, line 15
without any processing of the URL. In other words, the server is to without any processing of the URL. In other words, the server is to
hand back a complete URL and the client should not have to transform hand back a complete URL and the client should not have to transform
the URL to follow it. the URL to follow it.
For this application, such an example of a permanent move might be a For this application, such an example of a permanent move might be a
Top Level Domain (TLD) operator informing a client the information Top Level Domain (TLD) operator informing a client the information
being sought can be found with another TLD operator (i.e. a query for being sought can be found with another TLD operator (i.e. a query for
the domain bar in foo.example is found at http://foo.example/domain/ the domain bar in foo.example is found at http://foo.example/domain/
bar). bar).
For example, if the client sends http://serv1.example.com/weirds/ For example, if the client sends
domain/example.com, the server redirecting to https:// http://serv1.example.com/weirds/domain/example.com, the server
serv2.example.net/weirds2/ would set the Location: field to the redirecting to https://serv2.example.net/weirds2/ would set the
value: https://serv2.example.net/weirds2/domain/example.com. Location: field to the value:
https://serv2.example.net/weirds2/domain/example.com.
5.3. Negative Answers 5.3. Negative Answers
If a server wishes to respond that it has no information regarding If a server wishes to respond that it has an empty result set, it
the query, it returns a 404 response code. Optionally, it MAY returns a 404 response code. Optionally, it MAY include additional
include additional information regarding the negative answer in the information regarding the negative answer in the HTTP entity body.
HTTP entity body.
If a server wishes to inform the client that information about the If a server wishes to inform the client that information about the
query is available, but cannot include the information in the query is available, but cannot include the information in the
response to the client for policy reasons, the server MUST respond response to the client for policy reasons, the server MUST respond
with an appropriate response code out of HTTP's 4xx range. Clients with an appropriate response code out of HTTP's 4xx range. Clients
MAY retry the query based on the respective response code. MAY retry the query based on the respective response code.
5.4. Malformed Queries 5.4. Malformed Queries
If a server receives a query which it cannot interpret as an RDAP If a server receives a query which it cannot interpret as an RDAP
skipping to change at page 9, line 32 skipping to change at page 9, line 33
clients to process and display the data accordingly. clients to process and display the data accordingly.
The mechanism for including a language identifier in a response will The mechanism for including a language identifier in a response will
be defined in subsequent documents describing specific response be defined in subsequent documents describing specific response
formats. formats.
9.3. Language Identifiers in HTTP Headers 9.3. Language Identifiers in HTTP Headers
Given the description of the use of language identifiers in Given the description of the use of language identifiers in
Section 9.2, unless otherwise specified servers SHOULD ignore the Section 9.2, unless otherwise specified servers SHOULD ignore the
HTTP [RFC2616] Accept-Language header field when formulating HTTP HTTP [RFC7231] Accept-Language header field when formulating HTTP
entity responses, so that clients do not conflate the Accept-Language entity responses, so that clients do not conflate the Accept-Language
header with the 'lang' values in the entity body. header with the 'lang' values in the entity body.
However, servers MAY return language identifiers in the Content- However, servers MAY return language identifiers in the Content-
Language header field so as to inform clients of the intended Language header field so as to inform clients of the intended
language of HTTP layer messages. language of HTTP layer messages.
10. Contributing Authors and Acknowledgements 10. Contributing Authors and Acknowledgements
John Levine provided text to tighten up the Accept header field usage John Levine provided text to tighten up the Accept header field usage
and the text for the section on 429 responses. and the text for the section on 429 responses.
Marc Blanchet provided some clarifying text regarding the use of URLs Marc Blanchet provided some clarifying text regarding the use of URLs
with redirects, as well as very useful feedback during WGLC. with redirects, as well as very useful feedback during WGLC.
Normative language reviews were provided by Murray S. Kucherawy and Normative language reviews were provided by Murray S. Kucherawy and
Andrew Sullivan. Andrew Sullivan.
Jean-Phillipe Dionne provided text for the Security Considerations Jean-Phillipe Dionne provided text for the Security Considerations
section. section.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-httpbis-http2]
Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer
Protocol version 2", draft-ietf-httpbis-http2-14 (work in
progress), July 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005. Identifiers (IRIs)", RFC 3987, January 2005.
[RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status
Codes", RFC 6585, April 2012. Codes", RFC 6585, April 2012.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[W3C.CR-cors-20130129] [W3C.CR-cors-20130129]
Kesteren, A., "Cross-Origin Resource Sharing", World Wide Kesteren, A., "Cross-Origin Resource Sharing", World Wide
Web Consortium Candidate Recommendation CR-cors-20130129, Web Consortium Candidate Recommendation CR-cors-20130129,
January 2013, January 2013,
<http://www.w3.org/TR/2013/CR-cors-20130129>. <http://www.w3.org/TR/2013/CR-cors-20130129>.
11.2. Informative References 11.2. Informative References
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004. September 2004.
skipping to change at page 11, line 21 skipping to change at page 11, line 24
An example of an RDAP client and server exchange: An example of an RDAP client and server exchange:
Client: Client:
<TCP connect to rdap.example.com port 80> <TCP connect to rdap.example.com port 80>
GET /ip/203.0.113.0/24 HTTP/1.1 GET /ip/203.0.113.0/24 HTTP/1.1
Host: rdap.example.com Host: rdap.example.com
Accept: application/rdap+json Accept: application/rdap+json
rdap.example.com: rdap.example.com:
HTTP 301 Moved Permanently HTTP/1.1 301 Moved Permanently
Location: http://rdap-ip.example.com/ip/203.0.113.0/24 Location: http://rdap-ip.example.com/ip/203.0.113.0/24
Content-Length: 0 Content-Length: 0
Content-Type: application/rdap+json; charset=UTF-8 Content-Type: application/rdap+json
<TCP disconnect> <TCP disconnect>
Client: Client:
<TCP connect to rdap-ip.example.com port 80> <TCP connect to rdap-ip.example.com port 80>
GET /ip/203.0.113.0/24 HTTP/1.1 GET /ip/203.0.113.0/24 HTTP/1.1
Host: rdap-ip.example.com Host: rdap-ip.example.com
Accept: application/rdap+json Accept: application/rdap+json
rdap-ip.example.com: rdap-ip.example.com:
HTTP 200 OK HTTP/1.1 200 OK
Content-Type: application/rdap+json; charset=UTF-8 Content-Type: application/rdap+json
Content-Length: 9001 Content-Length: 9001
{ ... } { ... }
<TCP disconnect> <TCP disconnect>
Appendix B. Cache Busting Appendix B. Cache Busting
Some HTTP [RFC2616] cache infrastructure does not adhere to caching Some HTTP [RFC7231] cache infrastructure does not adhere to caching
standards adequately, and could cache responses longer than is standards adequately, and could cache responses longer than is
intended by the server. To overcome these issues, clients can use an intended by the server. To overcome these issues, clients can use an
adhoc and improbably used query parameter with a random value of adhoc and improbably used query parameter with a random value of
their choosing. As Section 4.2 instructs servers to ignore unknown their choosing. As Section 4.2 instructs servers to ignore unknown
parameters, this is unlikely to have any known side effects. parameters, this is unlikely to have any known side effects.
An example of using an unknown query parameter to bust caches: An example of using an unknown query parameter to bust caches:
http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123 http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123
skipping to change at page 14, line 4 skipping to change at page 14, line 6
* Corrected RFC 6839 as an informative reference. * Corrected RFC 6839 as an informative reference.
* Replaced MAYs with cans in Seciton 9.1. * Replaced MAYs with cans in Seciton 9.1.
* Replaced MAY with can in Appendix B. * Replaced MAY with can in Appendix B.
* Added a note in in Appendix C for the RFC Editor to remove this * Added a note in in Appendix C for the RFC Editor to remove this
section. section.
-07 -07
* Dropped reference to MUST with application/rdap+json * Dropped reference to MUST with application/rdap+json
* Dropped IANA registration of application/rdap+json * Dropped IANA registration of application/rdap+json
-08 -08
* Keep alive version. * Keep alive version.
-09
* Changed status lines in example to include http version number.
* Removed charset from media types in examples.
* Changed wording of 404 negative response to specifically say
"empty result set".
* Changed references to HTTP.
Authors' Addresses Authors' Addresses
Andrew Lee Newton Andrew Lee Newton
American Registry for Internet Numbers American Registry for Internet Numbers
3635 Concorde Parkway 3635 Concorde Parkway
Chantilly, VA 20151 Chantilly, VA 20151
US US
Email: andy@arin.net Email: andy@arin.net
URI: http://www.arin.net URI: http://www.arin.net
 End of changes. 21 change blocks. 
34 lines changed or deleted 56 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/