One document matched: draft-hollenbeck-weirds-rdap-search-00.txt
Network Working Group S. Hollenbeck
Internet-Draft Verisign Labs
Intended status: Standards Track A. Newton
Expires: July 29, 2013 ARIN
January 25, 2013
Registration Data Access Protocol Search Processing
draft-hollenbeck-weirds-rdap-search-00
Abstract
This document describes path segments and query parameters needed to
construct HTTP URLs that may be used to search for and retrieve
registration information from registries (including both Regional
Internet Registries (RIRs) and Domain Name Registries (DNRs)) using
"RESTful" web access patterns. It also describes a method of
encoding responses using Javascript Object Notation (JSON).
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 29, 2013.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Hollenbeck & Newton Expires July 29, 2013 [Page 1]
Internet-Draft RDAP Search January 2013
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Conventions Used in This Document . . . . . . . . . . . . . . . 3
1.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Query and Search Parameters . . . . . . . . . . . . . . . . . . 3
3.1. Domain Search . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Entity Search . . . . . . . . . . . . . . . . . . . . . . . 4
4. Search Processing . . . . . . . . . . . . . . . . . . . . . . . 4
5. Search Results . . . . . . . . . . . . . . . . . . . . . . . . 5
6. Internationalization Considerations . . . . . . . . . . . . . . 6
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
10.1. Normative References . . . . . . . . . . . . . . . . . . . 7
10.2. Informative References . . . . . . . . . . . . . . . . . . 8
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8
Hollenbeck & Newton Expires July 29, 2013 [Page 2]
Internet-Draft RDAP Search January 2013
1. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
1.1. Acronyms and Abbreviations
DNR: Domain Name Registry
RDAP: Registration Data Access Protocol
RIR: Regional Internet Registry
2. Introduction
This document describes a specification for registration data search
functions using a RESTful web service. The search functions are
implemented using the Hypertext Transfer Protocol (HTTP) [RFC2616].
Lookup processing as specified in [I-D.ietf-weirds-rdap-query] is
used when a client wishes to retrieve information associated with a
data object represented by a character string that exactly matches a
particular key. There is no provision for partial string pattern
matching to represent unknown characters or multiple result
possibilities. Experience with WHOIS [RFC3912] implementation and
operation has shown that people are often unsure of exact spellings
and they often want to receive multiple results that match a
particular pattern. This specification is intended to meet that need
for the Registration Data Access Protocol (RDAP).
3. Query and Search Parameters
RDAP search path segments are formed using a concatenation of the
plural form of the object being searched for, a forward slash
character ('/', ASCII value 0x002F), and an HTTP query string. The
HTTP query string is formed using a concatenation of the question
mark character ('?', ASCII value 0x003F), the JSON object value
associated with the object being searched for, the equal sign
character ('=', ASCII value 0x003D), and the search pattern. For the
domain and entity objects described in this document the plural
objects forms are "domains" and "entities". The JSON object value is
"name". One could construct a query string for an entity email
address using the "email" object name, but that is beyond the scope
of this specification.
Hollenbeck & Newton Expires July 29, 2013 [Page 3]
Internet-Draft RDAP Search January 2013
3.1. Domain Search
Syntax: domains/?name=<domain search pattern>
Searches for domain information are of the form /domains/?name=XXXX,
where XXXX is a search pattern representing a fully-qualified domain
name [RFC4343] in a zone administered by the server operator of a
DNR. (Open question: how do we do IDNs?) The following path would
be used to find DNR information for domain names matching the
"example*.com" pattern:
/domains/?name=example*.com
Note that this search is relevant to DNRs, not RIRs.
3.2. Entity Search
Syntax: entities/?name=<entity search pattern>
Searches for entity information are of the form /entities/?name=XXXX,
where XXXX is a search pattern representing an entity name as
specified in Section 7.1 of [I-D.ietf-weirds-json-response]. The
following path would be used to find DNR information for DNR entity
names matching the "Bobby Joe*" pattern.
/entities/?name=Bobby%20Joe*
URLs MUST be properly encoded according to the rules of [RFC3986].
In the example above, "Bobby Joe*" is encoded to "Bobby%20Joe*".
4. Search Processing
Searching occurs either on whole strings or on partial strings.
Partial string searching uses the asterisk ('*', ASCII value 0x002A)
character to match zero or more characters. The location or number
of occurances of the asterisk character is not dictated by this
specification. Some servers might support the asterisk in a trailing
location only (e.g. "/domains/example*.com") while others may allow
it a leading location (e.g. "/domains/*example.com"), or within
strings, or even in multiple locations.
If a server receives a search request but cannot process the request
because it does not support a particular style of partial match
searching, it SHOULD return an HTTP 500 error. When returning a 500
error, the server MAY also return an error response body as specified
in Section 12 of [I-D.ietf-weirds-json-response] if the requested
media type is that specified in [I-D.ietf-weirds-using-http]
Hollenbeck & Newton Expires July 29, 2013 [Page 4]
Internet-Draft RDAP Search January 2013
The search patterns described in this document MAY include non-ASCII
Unicode characters. This document does not specify partial matching
processing rules for Unicode or DNS u-label matching. Partial string
matching criteria for Unicode and DNS u-label characters is a matter
of local server policy. See Section 6 for guidelines that may be
used to develop local policies.
Clients SHOULD NOT submit search requests with partial matching for
DNS a-labels. A-labels represent an encoding that can only be
reconstructed properly when the label is complete.
5. Search Results
The method to return search results described here is not limited to
the /domains or /entities searches defined in this document. It can
also be used by future specifications to define search results for
other types of registration data.
Search results are returned in a JSON object. This object contains
data structures as outlined in Section 5 of
[I-D.ietf-weirds-json-response] (e.g. "rdapConformance", "notices",
etc...) and an array called "results" containing the objects that are
a result of the search. For the /domains (Section 3.1) and /entities
(Section 3.2) searches, the entity object class and the domain object
class are defined in [I-D.ietf-weirds-json-response].
To identify the type of object returned in the "results" array, each
object SHOULD contain a JSON string named "objectClass" (see Section
4.2 of [I-D.ietf-weirds-json-response] regarding the inclusion of new
JSON data in object classes). For domains, the string MUST be
"domain" and for entities the string MUST be "entity".
Servers SHOULD signify their compliance with this specification by
including the string "domain_entity_search_level_0" in the
"rdapConformance" array.
Hollenbeck & Newton Expires July 29, 2013 [Page 5]
Internet-Draft RDAP Search January 2013
{
"rdapConformance" :
[
"rdap_level_0",
"domain_entity_search_level_0"
],
...
"results" :
[
{
"handle" : "1-XXXX",
"name" : "1.example.com",
"objectClass" : "domain",
...
},
{
"handle" : "2-XXXX",
"name" : "2.example.com",
"objectClass" : "domain",
...
}
]
}
Figure 1
6. Internationalization Considerations
TBD. Give guidelines for how a local policy could work for
searching.
7. IANA Considerations
This document does not specify any IANA actions.
8. Security Considerations
Security services for the operations specified in this document are
described in "Security Services for the Registration Data Access
Protocol" [I-D.ietf-weirds-rdap-sec]. As we identify specific use
cases for which security services are needed they will be described
here.
Hollenbeck & Newton Expires July 29, 2013 [Page 6]
Internet-Draft RDAP Search January 2013
9. Acknowledgements
The authors would like to acknowledge the following individuals for
their contributions to this document: TBD.
10. References
10.1. Normative References
[I-D.ietf-weirds-json-response]
Newton, A. and S. Hollenbeck, "JSON Responses for the
Registration Data Access Protocol (RDAP)",
draft-ietf-weirds-json-response-02 (work in progress),
January 2013.
[I-D.ietf-weirds-rdap-query]
Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol Query Format", draft-ietf-weirds-rdap-query-02
(work in progress), December 2012.
[I-D.ietf-weirds-rdap-sec]
Hollenbeck, S. and N. Kong, "Security Services for the
Registration Data Access Protocol",
draft-ietf-weirds-rdap-sec-01 (work in progress),
November 2012.
[I-D.ietf-weirds-using-http]
Newton, A., Ellacott, B., and N. Kong, "Using the
Registration Data Access Protocol (RDAP) with HTTP",
draft-ietf-weirds-using-http-01 (work in progress),
December 2012.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
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
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity
Clarification", RFC 4343, January 2006.
Hollenbeck & Newton Expires July 29, 2013 [Page 7]
Internet-Draft RDAP Search January 2013
10.2. Informative References
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004.
Appendix A. Change Log
Initial -00: First draft individual submission.
Authors' Addresses
Scott Hollenbeck
Verisign Labs
12061 Bluemont Way
Reston, VA 20190
US
Email: shollenbeck@verisign.com
URI: http://www.verisignlabs.com/
Andrew Lee Newton
American Registry for Internet Numbers
3635 Concorde Parkway
Chantilly, VA 20151
US
Email: andy@arin.net
URI: http://www.arin.net
Hollenbeck & Newton Expires July 29, 2013 [Page 8]
| PAFTECH AB 2003-2026 | 2026-04-24 04:42:34 |