draft-ietf-weirds-using-http-12.txt   draft-ietf-weirds-using-http-13.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: March 28, 2015 APNIC Expires: April 10, 2015 APNIC
N. Kong N. Kong
CNNIC CNNIC
September 24, 2014 October 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-12 draft-ietf-weirds-using-http-13
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). RDAP is a transported using the Hypertext Transfer Protocol (HTTP). RDAP is a
successor protocol to the very old WHOIS protocol. The purpose of successor protocol to the very old WHOIS protocol. The purpose of
this document is to clarify the use of standard HTTP mechanisms for this document is to clarify the use of standard HTTP mechanisms for
this application. this application.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 March 28, 2015. This Internet-Draft will expire on April 10, 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 3, line 27 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 (e.g. bash and wget). scripting tools (e.g. bash and wget).
This is the basic usage pattern for this protocol: This is the basic usage pattern for this protocol:
1. A client determines an appropriate server to query. Once such 1. A client determines an appropriate server to query along with the
method is described in [I-D.ietf-weirds-bootstrap]. See appropriate base URL to use in such queries.
Appendix C. [I-D.ietf-weirds-bootstrap] describes one method to determine the
server and the base URL. See Appendix C for more information.
2. A client issues an HTTP (or HTTPS) query using GET [RFC7231]. As 2. A client issues an HTTP (or HTTPS) query using GET [RFC7231]. As
an example, a query for the network registration 192.0.2.0 might an example, a query for the network registration 192.0.2.0 might
be be
http://example.com/ip/192.0.2.0 http://example.com/rdap/ip/192.0.2.0
[I-D.ietf-weirds-rdap-query] details the various queries used in [I-D.ietf-weirds-rdap-query] details the various queries used in
RDAP. RDAP.
3. If the receiving server has the information for the query, it 3. 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. [I-D.ietf-weirds-json-response] details a response in format. [I-D.ietf-weirds-json-response] details a response in
JavaScript Object Notation (JSON). Other, non-standard, formats JavaScript Object Notation (JSON).
may be used as well.
4. If the receiving server does not have the information for the 4. 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
Resource Locator) pointing to the information or another server Resource Locator) pointing to the information or another server
known to have knowledge of the location of the information. The known to have knowledge of the location of the information. The
client is expected to re-query using that HTTP URL. client is expected to re-query using that HTTP URL.
5. If the receiving server does not have the information being 5. If the receiving server does not have the information being
skipping to change at page 5, line 25 skipping to change at page 5, line 25
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 web services styled after REST [REST], of client behaviours for web services styled after REST [REST],
reducing the cost to deploy Registration Data Directory Services and reducing the cost to deploy Registration Data Directory Services and
clients. clients.
4. Queries 4. Queries
4.1. HTTP Methods 4.1. HTTP Methods
Clients SHOULD use either the HTTP GET or HEAD methods (see Clients use the GET method to retrieve a response body and use the
[RFC7231]). The GET method can be used to retrieve a response body. HEAD method to determine existence of data on the server. Clients
The HEAD method can be used to determine existence of data on the SHOULD use either the HTTP GET or HEAD methods (see [RFC7231]).
server. Servers are under no obligation to support other HTTP Servers are under no obligation to support other HTTP methods,
methods, therefore clients using other methods will likely not therefore clients using other methods will likely not interoperate
interoperate properly. properly.
Clients MUST support HTTPS as well as HTTP. Clients MUST support HTTPS as well as HTTP.
4.2. Accept Header 4.2. Accept Header
To indicate to servers that an RDAP response is desired, clients To indicate to servers that an RDAP response is desired, clients
include an Accept: header field with an RDAP specific JSON media include an Accept: header field with an RDAP specific JSON media
type, the generic JSON media type, or both. Servers receiving an type, the generic JSON media type, or both. Servers receiving an
RDAP request return an entity with a Content-Type: header containing RDAP request return an entity with a Content-Type: header containing
the RDAP specific JSON media type. the RDAP specific JSON media type.
skipping to change at page 6, line 9 skipping to change at page 6, line 9
4.3. Query Parameters 4.3. Query Parameters
Servers MUST ignore unknown query parameters. Use of unknown query Servers MUST ignore unknown query parameters. Use of unknown query
parameters for cache-busting is described in Appendix B. parameters for cache-busting is described in Appendix B.
5. Types of HTTP Response 5. Types of HTTP Response
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, this section defines the minimal set of response codes in
described in this section as they will be in common use by servers. common use by servers that a client will need to understand. While
While some clients may be constructed with simple tooling that does some clients may be constructed with simple tooling that does not
not account for all of these response codes, a more robust client account for all of these response codes, a more robust client
accounting for these codes will likely provide a better user accounting for these codes will likely provide a better user
experience. It is expected that usage of response codes and types experience. It is expected that usage of response codes and types
for this application not defined here will be described in subsequent for this 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 returns that answer in the body of a 200 response. it returns that answer in the body of a 200 response.
skipping to change at page 7, line 32 skipping to change at page 7, line 32
query, it returns a 400 response code. Optionally, it MAY include query, it returns a 400 response code. Optionally, it MAY include
additional information regarding this negative answer in the HTTP additional information regarding this negative answer in the 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 returns a 429 response code as described in [RFC6585]. A client it returns a 429 response code as described in [RFC6585]. A client
that receives a 429 response SHOULD decrease its query rate, and that receives a 429 response SHOULD decrease its query rate, and
honor the Retry-After header field if one is present. Clients that honor the Retry-After header field if one is present. Servers may
do not honor the Retry-After header may stricter limits placed upon place stricter limits upon clients that do not honor the Retry-After
them. header.
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 24 skipping to change at page 10, line 24
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.
The mechanism for including a language identifier in a response will [I-D.ietf-weirds-json-response] provides such a mechanism.
be defined in subsequent documents describing specific response
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 [RFC7231] 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-
skipping to change at page 11, line 20 skipping to change at page 11, line 20
This document is the work product of the IETF's WEIRDS working group, This document is the work product of the IETF's WEIRDS working group,
of which Olaf Kolkman and Murray Kucherawy were chairs. of which Olaf Kolkman and Murray Kucherawy were chairs.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-weirds-bootstrap] [I-D.ietf-weirds-bootstrap]
Blanchet, M. and G. Leclanche, "Finding the Authoritative Blanchet, M. and G. Leclanche, "Finding the Authoritative
Registration Data (RDAP) Service", draft-ietf-weirds- Registration Data (RDAP) Service", draft-ietf-weirds-
bootstrap-06 (work in progress), September 2014. bootstrap-07 (work in progress), September 2014.
[I-D.ietf-weirds-json-response] [I-D.ietf-weirds-json-response]
Newton, A. and S. Hollenbeck, "JSON Responses for the Newton, A. and S. Hollenbeck, "JSON Responses for the
Registration Data Access Protocol (RDAP)", draft-ietf- Registration Data Access Protocol (RDAP)", draft-ietf-
weirds-json-response-08 (work in progress), August 2014. weirds-json-response-09 (work in progress), September
2014.
[I-D.ietf-weirds-rdap-query] [I-D.ietf-weirds-rdap-query]
Newton, A. and S. Hollenbeck, "Registration Data Access Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol Query Format", draft-ietf-weirds-rdap-query-13 Protocol Query Format", draft-ietf-weirds-rdap-query-14
(work in progress), August 2014. (work in progress), September 2014.
[I-D.ietf-weirds-rdap-sec] [I-D.ietf-weirds-rdap-sec]
Hollenbeck, S. and N. Kong, "Security Services for the Hollenbeck, S. and N. Kong, "Security Services for the
Registration Data Access Protocol", draft-ietf-weirds- Registration Data Access Protocol", draft-ietf-weirds-
rdap-sec-08 (work in progress), August 2014. rdap-sec-09 (work in progress), September 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.
[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.
skipping to change at page 13, line 9 skipping to change at page 13, line 11
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. The media type used here is is not described in this document. The media type used here is
described in [I-D.ietf-weirds-json-response]. described in [I-D.ietf-weirds-json-response].
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 /rdap/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/1.1 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/rdap/ip/203.0.113.0/24
Content-Length: 0 Content-Length: 0
Content-Type: application/rdap+json 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 /rdap/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/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/rdap+json Content-Type: application/rdap+json
Content-Length: 9001 Content-Length: 9001
{ ... } { ... }
<TCP disconnect> <TCP disconnect>
skipping to change at page 19, line 5 skipping to change at page 18, line 49
* Numerous textual clarifications. * Numerous textual clarifications.
* Added an actual reference to RFC 5226 instead of just talking * Added an actual reference to RFC 5226 instead of just talking
about it. about it.
* A reference to draft-ietf-weirds-bootstrap was added. * A reference to draft-ietf-weirds-bootstrap was added.
* Included a section on redirectors. * Included a section on redirectors.
-13
* Addressed AD feedback.
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. 19 change blocks. 
34 lines changed or deleted 37 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/