draft-ietf-weirds-using-http-05.txt   draft-ietf-weirds-using-http-06.txt 
Network Working Group A.L. Newton Network Working Group A. Newton
Internet-Draft ARIN Internet-Draft ARIN
Intended status: Standards Track B.J. Ellacott Intended status: Standards Track B. Ellacott
Expires: November 14, 2013 APNIC Expires: December 20, 2013 APNIC
N. Kong N. Kong
CNNIC CNNIC
May 13, 2013 June 18, 2013
HTTP usage in the Registration Data Access Protocol (RDAP) HTTP usage in the Registration Data Access Protocol (RDAP)
draft-ietf-weirds-using-http-05 draft-ietf-weirds-using-http-06
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).
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
skipping to change at page 1, line 35 skipping to change at page 1, line 35
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 November 14, 2013. This Internet-Draft will expire on December 20, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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 39 skipping to change at page 2, line 39
5.6. Cross-Origin Resource Sharing . . . . . . . . . . . . . . 7 5.6. Cross-Origin Resource Sharing . . . . . . . . . . . . . . 7
6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7
7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
8.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 8 8.1. RDAP Extensions Registry . . . . . . . . . . . . . . . . 8
8.2. RDAP Media Type Registration . . . . . . . . . . . . . . 9 8.2. RDAP Media Type Registration . . . . . . . . . . . . . . 9
9. Internationalization Considerations . . . . . . . . . . . . . 10 9. Internationalization Considerations . . . . . . . . . . . . . 10
9.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 10 9.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 10
9.2. Language Identifiers in Queries and Responses . . . . . . 10 9.2. Language Identifiers in Queries and Responses . . . . . . 10
9.3. Language Identifiers in HTTP Headers . . . . . . . . . . 10 9.3. Language Identifiers in HTTP Headers . . . . . . . . . . 10
10. Contributing Authors and Acknowledgements . . . . . . . . . . 10 10. Contributing Authors and Acknowledgements . . . . . . . . . . 11
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
11.1. Normative References . . . . . . . . . . . . . . . . . . 11 11.1. Normative References . . . . . . . . . . . . . . . . . . 11
11.2. Informative References . . . . . . . . . . . . . . . . . 11 11.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 12 Appendix A. Protocol Example . . . . . . . . . . . . . . . . . . 12
Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 13 Appendix B. Cache Busting . . . . . . . . . . . . . . . . . . . 13
Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 13 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
This document describes the usage of HTTP for Registration Data This document describes the usage of HTTP for Registration Data
Directory Services. The goal of this document is to tie together Directory Services. The goal of this document is to tie together
usage patterns of HTTP into a common profile applicable to the usage patterns of HTTP into a common profile applicable to the
various types of Directory Services serving Registration Data using various types of Directory Services serving Registration Data using
RESTful practices. By giving the various Directory Services common RESTful practices. By giving the various Directory Services common
behavior, a single client is better able to retrieve data from behavior, a single client is better able to retrieve data from
Directory Services adhering to this behavior. Directory Services adhering to this behavior.
skipping to change at page 4, line 50 skipping to change at page 4, line 50
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 known query/response model used by HTTP
[RFC2616]. Should an entity contain more than one result, some of [RFC2616]. 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, multiple response formats are supported by this protocol. At Second, the semantics of the request/response allow for future and/or
present the IETF Web Extensible Internet Data Service (WEIRDS) non-standard response formats. In this document, only a JSON
working group is defining only a JSON [RFC4627] response format, but [RFC4627] response media type is defined, with the response contents
server operators may use other data formats when those formats are to be described separately. This document only describes how RDAP is
requested. 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
of mechanisms available for use with HTTP. HTTP offers a number of of mechanisms available for use with HTTP. HTTP offers a number of
mechanisms not described further in this document. Operators are mechanisms not described further in this document. Operators are
able to make use of these mechanisms according to their local policy, able to make use of these mechanisms according to their local policy,
including cache control, authorization, compression, and redirection. including cache control, authorization, compression, and redirection.
HTTP also benefits from widespread investment in scalability, HTTP also benefits from widespread investment in scalability,
reliability, and performance, and widespread programmer understanding reliability, and performance, and widespread programmer understanding
of client behaviours for RESTful web services, reducing the cost to of client behaviours for RESTful web services, reducing the cost to
deploy Registration Data Directory Services and clients. deploy Registration Data Directory Services and clients.
skipping to change at page 6, line 4 skipping to change at page 5, line 47
This section describes the various types of responses a server may This section describes the various types of responses a server may
send to a client. While no standard HTTP response code is forbidden send to a client. While no standard HTTP response code is forbidden
in usage, at a minimum clients SHOULD understand the response codes in usage, at a minimum clients SHOULD understand the response codes
described in this section as they will be in common use by servers. described in this section as they will be in common use by servers.
It is expected that usage of response codes and types for this It is expected that usage of response codes and types for this
application not defined here will be described in subsequent application not defined here will be described in subsequent
documents. documents.
5.1. Positive Answers 5.1. Positive Answers
If a server has the information requested by the client and wishes to If a server has the information requested by the client and wishes to
respond to the client with the information according to its policies, respond to the client with the information according to its policies,
it encodes the answer in the format most appropriate according to the it returns that answer in the body of a 200 response.
standard and defined rules for processing the HTTP Accept header
field, and return that answer in the body of a 200 response.
5.2. Redirects 5.2. Redirects
If a server wishes to inform a client that the answer to a given If a server wishes to inform a client that the answer to a given
query can be found elsewhere, it MUST return a 301 response code to query can be found elsewhere, it returns either a 301 response code
indicate a permanent move, or a 307 response code to indicate a non- to indicate a permanent move, or a 302, 303 or 307 response code to
permanent redirection, and include an HTTP(s) URL in the Location: indicate a non-permanent redirection, and it includes an HTTP(s) URL
header field. The client is expected to issue a subsequent request in the Location: header field. The client is expected to issue a
to satisfy the original query using the given URL without any subsequent request to satisfy the original query using the given URL
processing of the URL. In other words, the server is to hand back a without any processing of the URL. In other words, the server is to
complete URL and the client should not have to transform the URL to hand back a complete URL and the client should not have to transform
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 being sought can be found with another TLD operator (i.e. a query for
for the domain bar in foo.example is found at http://foo.example/ the domain bar in foo.example is found at http://foo.example/domain/
domain/bar). bar).
For example, if the client sends http://serv1.example.com/weirds/ For example, if the client sends http://serv1.example.com/weirds/
domain/example.com, the server redirecting to https:// domain/example.com, the server redirecting to https://
serv2.example.net/weirds2/ would set the Location: field to the serv2.example.net/weirds2/ would set the Location: field to the
value: https://serv2.example.net/weirds2/domain/example.com. 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 no information regarding
the query, it MUST return a 404 response code. Optionally, it MAY the query, it returns a 404 response code. Optionally, it MAY
include additional information regarding the negative answer in the include additional 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
query, it MUST return a 400 response code. Optionally, it MAY query, it returns a 400 response code. Optionally, it MAY include
include additional information regarding this negative answer in the additional information regarding this negative answer in the HTTP
HTTP entity body. entity body.
5.5. Rate Limits 5.5. Rate Limits
Some servers apply rate limits to deter address scraping and other Some servers apply rate limits to deter address scraping and other
abuses. When a server declines to answer a query due to rate limits, abuses. When a server declines to answer a query due to rate limits,
it SHOULD return a 429 response code as described in [RFC6585]. A it returns a 429 response code as described in [RFC6585]. A client
client that receives a 429 response SHOULD decrease its query rate, that receives a 429 response SHOULD decrease its query rate, and
and honor the Retry-After header field if one is present. honor the Retry-After header field if one is present.
Note that this is not a defense against denial-of-service attacks, Note that this is not a defense against denial-of-service attacks,
since a malicious client could ignore the code and continue to send since a malicious client could ignore the code and continue to send
queries at a high rate. A server might use another response code if queries at a high rate. A server might use another response code if
it did not wish to reveal to a client that rate limiting is the it did not wish to reveal to a client that rate limiting is the
reason for the denial of a reply. reason for the denial of a reply.
5.6. Cross-Origin Resource Sharing 5.6. Cross-Origin Resource Sharing
When responding to queries, it is RECOMMENDED that servers use the When responding to queries, it is RECOMMENDED that servers use the
skipping to change at page 10, line 16 skipping to change at page 10, line 16
Author: Andy Newton Author: Andy Newton
Change controller: IETF Change controller: IETF
Provisional Registration: No (upon publication of this RFC) Provisional Registration: No (upon publication of this RFC)
9. Internationalization Considerations 9. Internationalization Considerations
9.1. URIs and IRIs 9.1. URIs and IRIs
Clients MAY use IRIs [RFC3987] as they see fit, but MUST transform Clients can use IRIs [RFC3987] for internal use as they see fit, but
them to URIs [RFC3986] for interaction with RDAP servers. RDAP MUST transform them to URIs [RFC3986] for interaction with RDAP
servers MUST use URIs in all responses, and clients MAY transform servers. RDAP servers MUST use URIs in all responses, and again
these URIs to IRIs. clients can transform these URIs to IRIs for internal use as they see
fit.
9.2. Language Identifiers in Queries and Responses 9.2. Language Identifiers in Queries and Responses
Under most scenarios, clients requesting data will not signal that Under most scenarios, clients requesting data will not signal that
the data be returned in a particular language or script. On the the data be returned in a particular language or script. On the
other hand, when servers return data and have knowledge that the data other hand, when servers return data and have knowledge that the data
is in a language or script, the data SHOULD be annotated with is in a language or script, the data SHOULD be annotated with
language identifiers whenever they are available, thus allowing language identifiers whenever they are available, thus allowing
clients to process and display the data accordingly. clients to process and display the data accordingly.
skipping to change at page 11, line 8 skipping to change at page 11, line 13
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
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
skipping to change at page 11, line 35 skipping to change at page 11, line 40
[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.
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839, January 2013.
[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 12, line 12 skipping to change at page 12, line 12
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5890] Klensin, J., "Internationalized Domain Names for [RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010. RFC 5890, August 2010.
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839, January 2013.
[SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS [SAC-051] Piscitello, D., Ed., "SSAC Report on Domain Name WHOIS
Terminology and Structure", September 2011. Terminology and Structure", September 2011.
Appendix A. Protocol Example Appendix A. Protocol Example
To demonstrate typical behaviour of an RDAP client and server, the To demonstrate typical behaviour of an RDAP client and server, the
following is an example of an exchange, including a redirect. The following is an example of an exchange, including a redirect. The
data in the response has been elided for brevity, as the data format data in the response has been elided for brevity, as the data format
is not described in this document. is not described in this document.
skipping to change at page 13, line 9 skipping to change at page 13, line 36
Content-Type: application/rdap+json; charset=UTF-8 Content-Type: application/rdap+json; charset=UTF-8
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 [RFC2616] 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 MAY 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
Use of an unknown parameter to overcome misbehaving caches is not Use of an unknown parameter to overcome misbehaving caches is not
part of any specification and is offered here for informational part of any specification and is offered here for informational
purposes. purposes.
Appendix C. Changelog Appendix C. Changelog
RFC Editor: Please remove this section.
Initial WG -00: Updated to working group document 2012-September-20 Initial WG -00: Updated to working group document 2012-September-20
-01 -01
* Updated for the sections moved to the JSON responses draft. * Updated for the sections moved to the JSON responses draft.
* Simplified media type, removed "level" parameter. * Simplified media type, removed "level" parameter.
* Updated 2119 language and added boilerplate. * Updated 2119 language and added boilerplate.
skipping to change at page 14, line 43 skipping to change at page 15, line 24
-05 -05
* Update the media type registration. * Update the media type registration.
* Further explained the SHOULD in section 5. * Further explained the SHOULD in section 5.
* Split the references into normative and informative. * Split the references into normative and informative.
* Other minor fixes. * Other minor fixes.
-06
* Rewritten the third paragraph in Section 3 to avoid
contradictions
* Simplified the wording in Seciton 5.1.
* Removed some RFC 2119 words in Section 5.2, 5.3, 5.4 and 5.5.
* Corrected RFC 6839 as an informative reference.
* Replaced MAYs with cans in Seciton 9.1.
* Replaced MAY with can in Appendix B.
* Added a note in in Appendix C for the RFC Editor to remove this
section.
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. 22 change blocks. 
44 lines changed or deleted 64 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/