Using HTTP for RESTful Whois Services by Internet Registries
American Registry for Internet Numbers3635 Concorde ParkwayChantillyVAUS20151andy@arin.nethttp://www.arin.netRIPE Network Coordination CentreSingel 258AmsterdamNL1016ABkranjbar@ripe.nethttp://www.ripe.netLatin American and Caribbean Internet Address
RegistryRambla Republica de Mexico 6125MontevideoUY11300aservin@lacnic.nethttp://www.lacnic.netAsia Pacific Network Information Center6 Cordelia StreetSouth BrisbaneAustraliaQLD 4101bje@apnic.nethttp://www.apnic.netVerisign Labs12061 Bluemont WayRestonVAUS20190shollenbeck@verisign.comhttp://www.verisignlabs.com/
Internet Corporation for Assigned Names and Numbers
4676 Admiralty Way, Suite 330United States of America90292Marina del Rey, CA +1.310.823.9358steve.sheng@icann.org
Internet Corporation for Assigned Names and Numbers
4676 Admiralty Way, Suite 330United States of America90292Marina del Rey, CA+1.310.823.9358francisco.arias@icann.org
China Internet Network Information Center
4 South 4th Street, Zhongguancun, Haidian District China100190Beijing+86 10 5881 3147nkong@cnnic.cn
Internet Systems Consortium
950 Charter StUnited States of America94063Redwood City, CA+1.650.423.1374fobispo@isc.org This document describes the use of HTTP in Whois services using
RESTful web methodologies.
This document describes the usage of HTTP for Registration Data Directory Services
running on RESTful web servers. The goal of this document is to tie together the
usage patterns of HTTP into a common profile applicable to the various types of
Directory Services serving Registration Data using RESTful styling. By giving the
various Directory Services common behavior, a single client is better able to
retrieve data from Directory Services adhering to this behavior.
In designing these common usage patterns, this draft endeavours to satisfy
requirements for Registration Data Access Protocols that are documented in
. This draft also introduces an
additional design consideration to define a simple use of HTTP. Where complexity may
reside, it is the goal of this specification to place it upon the server and to keep
the client as simple as possible. A client should be possible using common operating
system scripting tools.
This is the basic usage pattern for this protocol:
A client issues an HTTP query using GET. As an example, a query for
the network registration 192.168.0.0 might be http://example.com/ip/192.168.0.0.If the receiving server has the information for the query, it examines
the Accept header field of the query and returns a 200 response with a response
entity appropriate for the requested format.If the receiving server does not have the information for the query but does
have knowledge of where the information can be found, it will return a
redirection response (3xx) with the Redirect header containing an HTTP URL pointing
to the information. The client is expected to re-query using that HTTP URL.If the receiving server does not have the information being requested and
does not have knowledge of where the information can be found, it should
return a 404 response.
It is important to note that it is not the intent of this document to redefine the
meaning and semantics of HTTP. The purpose of this document is to clarify the use
of standard HTTP mechanisms for this application.
As is noted in SSAC Report on WHOIS Terminology and Structure,
the term "Whois" is overloaded, often referring to a protocol, a service and data.
In accordance with , this document describes the base
behavior for a Registration Data Access Protocol (RD-AP). At present, there are two
known types of RD-AP, a Domain Name Registration Data Access Protocol (DNRD-AP) and a
Number Resource Registration Data Access Protocol (NRRD-AP). Both the DNRD-AP and
NRRD-AP are to be built upon this base behavior, the RD-AP.
Note that other types of RD-AP may exist in the future.
There are a few design criteria this document attempts to support.
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 is simplified to the
known query/respone model used by HTTP.
Should a result contain more than one result,
some of which are better served by other servers, the redirection model becomes
much more complicated.
Second, multiple response formats are supported by this protocol. This document
outlines the base usage of JSON and XML, but server operators may support other
formats as they desire if appropriate.
Third, HTTP offers a number of transport protocol mechanisms not described further
in this document. Operators are able to make use of these mechanisms according to
their local policy, including cache control, authorization, compression, and
redirection. HTTP also benefits from widespread investment in scalability,
reliability, and performance, and widespread programmer understanding of client
behaviours for RESTful web services, reducing the cost to deploy Registration Data
Directory Services and clients.
Clients SHOULD put the media type of the format they desire in
the Accept header field, and SHOULD use the Accept header parameter
"level" to indicate the version of the format acceptable .
Servers SHOULD respond with an appropriate media type
in the Content-Type header in accordance with the preference rules for the Accept
header in HTTP. Servers SHOULD affix
a media type parameter of "level" appropriate to the version of the format
being sent.
Clients MAY use a generic media type for the desired data format of the
response (e.g. "application/json"), but servers SHOULD respond with the most
appropriate media type and corresponding level (e.g. "application/weirds+json;level=0").
In other words, a client may use "application/json" to express that it
desires JSON or "application/weirds_blah+json" to express that it
desires WEIRDS BLAH in JSON. The server MUST respond with
"application/weirds_blah+json;level=0".
Servers SHOULD ignore unknown query parameters. Use of unknown query
parameters for cache-busting is described in .
This section describes the various types of responses a server may send to a client.
While no standard HTTP response code is forbidden in usage, at a minimum clients
should understand the response codes described in this section. It is expected that
usage of response codes and types for this application not defined here will be
described in subsequent documents.
If a server has the information requested by the client and wishes to respond
to the client with the information according to its policies, it should encode
the answer in the format most appropriate according to the standard and defined
rules for processing the HTTP Accept header, and return that answer in
the body of a 200 response.
If a server wishes to inform a client that the answer to a given query can be found
elsewhere, it SHOULD return either a 301 or a 307 response code and an HTTP URL in
the Redirect header. The client is expected to issue a subsequent query using the
given URL 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 the URL to follow it.
A server should use a 301 response to inform the client of a permanent move and a
307 response otherwise. For this application, such an example of a permanent move
might be a TLD operator informing a client the information 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/bar).
If a server wishes to respond that it has no information regarding the query,
it SHOULD return a 404 response code. Optionally, it may include additional
information regarding the lack of information as defined by
.
If a server receives a query which it cannot understand, it SHOULD return
a 400 response code. Optionally, it may include additional information about
why it does not understand the query as defined by .
Clients may signal their desire for JSON using the "application/json" media type
or a more application specific JSON media type.
Clients processing JSON responses SHOULD ignore
values associated with unrecognized
names. Servers MAY insert values signified by names into the JSON responses which
are not specified in this document. Insertion of unspecified values into JSON
responses SHOULD have names prefixed with a short identifier followed by an
underscore followed by a meaningful name. For example, a JSON object may have "handle" and "remarks" formally documented
in a specification. Clients adhering to that specification will have
appropriate knowledge of the meaning of "handle" and "remarks".
If The Registry of the Moon desires to express information not found in
the specification, it might select "lunarNic" as its identifying prefix and insert,
as an example, the name "lunarNic_beforeOneSmallStep" to signify registrations
occuring before the first moon landing and the name "lunarNic_harshMistressNotes"
containing other descriptive text.
Insertion of unrecognized names ignored by clients may also be used for
future revisions to specifications and specifications deriving extensions from
a base specification.
JSON names SHOULD only consist of the alphabetic ASCII characters A through Z in
both uppercase and lowercase, the numerical digits 0 through 9, underscore
characters, and SHOULD NOT begin with
an underscore character, numerical digit or the characters "xml". The following
describes the produciton of JSON names in ABNF. This restriction
is a union
of the Ruby programming language identifier syntax and the XML element name
syntax and has two purposes. First, client implementers using modern programming
languages such as Ruby or Java may use libraries that automatically promote JSON
names to first order object attributes or members (e.g. using the example above,
the values may be referenced as network.handle or network.lunarNic_beforeOneSmallStep).
Second, a clean mapping between JSON and XML is easy to accomplish using the JSON
representation.
Clients processing JSON responses MUST be prepared for values specified in the
registry response documents to be absent from a response as no JSON value
listed is required to appear in the response. In other words, servers MAY remove
values as is needed by the policies of the server operator.
Clients may signal their desire for XML using the "application/xml" media type
or a more application specific XML media type.
Well-formed XML may be programmatically produced using the JSON encodings
due to the JSON naming rules outlined in and
the following simple rules:
Where a JSON name is given, the corresponding XML element has the
same name.Where a JSON value is found, it is the content of the corresponding
XML element.Where a JSON value is an array, the XML element is to be repeated
for each element of the array.The root tag of the XML document is to be "response".
JSON values converted to XML element content MUST be properly
escaped. XML offers various means for escaping data, but such escaping
MUST account for the '<', '>', and '&' characters and
MUST redact all C0 control characters except tab, carriage return, and
new-line. (Redaction of disallowed control characters is a protocol
requirement, though in practice most Internet registries do not allow
this data in their data stores and therefore do not need to account
for this rule.)
The rules for clients processing XML responses are the same as those with
JSON: clients SHOULD ignore unrecognized XML elements, and servers MAY insert
XML elements with tag names according to the naming rules in
. And as with JSON, clients MUST be prepared for
XML elements specified in the
registry response documents to be absent from a response as no XML element
listed is required to appear in the response.
As specified in , some non-answer responses may
return entity bodies with information that could be more descriptive.
The basic structure of that response is a data class containing an error code
number (corresponding to the HTTP response code) followed by a string named
"title" followed by an array of strings named "description".
The media type for the JSON structure is "application/rdap_error+json" and
the media type for the XML document is "application/rdap_error+xml". Conformance
to this specification is considered to be level 0 for both media types.
A client MAY simply use the HTTP response code as the server is not required to
include error data in the response body. However, if a client wishes to parse the
error data, it SHOULD first check that the Content-Type header contains the appropriate
media type.
This section defines two common data structures to be used by DNRD-AP, NRRD-AP, and
other RD-AP protocols. As such, the names identifying these data structures are not to be
redefined by any registry specific RD-AP specifications. Each of these datatypes MAY
appear within any other data object of a response, but the intended purpose is that they
will be mostly used in the top-most data object of a response.
The first data structure is named "rdapConformance" and is simply an array of
strings, each providing a hint as to the specifications used in the construction
of the response.
The second data structure is named "notices" and is an array of "notice"
objects. Each "notice" object contains a "title" string representing the
title of the notice object, an array of strings named "description" for the
purposes of conveying any descriptive text about the notice, and a "uri"
string holding a URI referencing a service that may provide additional
information about the notice.
This section describes common data types found in Internet registries, the
purpose being a common and normalized list of normative references to
other specifications to be used by multiple RD-AP applications. Unless otherwise
stated by the response specification of an Internet registry using this specification
as a basis, the data types can assume to be as follows:
IPv4 addresses - IPv6 addresses - country code - domain name - email address - date and time strings -
This specification registers the "application/rdap_error+json" media type.
Type name: applicationSubtype name: rdap_error+jsonRequired parameters: n/aOptional parameters: levelEncoding considerations: n/aSecurity considerations: n/aInteroperability considerations: n/aPublished specification: [[ this document ]]Applications that use this media type: RESTful Whois applicationsAdditional information: n/aPerson & email address to contact for further information: Andy Newton &andy@hxr.us&Intended usage: COMMONRestrictions on usage: noneAuthor: Andy NewtonChange controller: IETF
This specification registers the "application/rdap_error+xml" media type.
Type name: applicationSubtype name: rdap_error+xmlRequired parameters: n/aOptional parameters: levelEncoding considerations: n/aSecurity considerations: n/aInteroperability considerations: n/aPublished specification: [[ this document ]]Applications that use this media type: RESTful Whois applicationsAdditional information: n/aPerson & email address to contact for further information: Andy Newton &andy@hxr.us&Intended usage: COMMONRestrictions on usage: noneAuthor: Andy NewtonChange controller: IETF
Clients MAY use IRIs as they see fit, but MUST transform them to
URIs for interaction with RD-AP servers.
RD-AP servers MUST use URIs in all responses, and clients MAY transform
these URIs to IRIs.
The default text encoding for JSON and XML responses in RD-AP is UTF-8,
and all servers and clients MUST support UTF-8. Servers and clients MAY
optionally support other character encodings.
Requirements For Internet Registry ServicesCloudmarkSSAC Report on Domain Name WHOIS Terminology and StructureThe application/json Media Type for JavaScript Object Notation
(JSON)JavaScript Object Notation (JSON) is a lightweight, text-based,
language-independent data interchange format. It was derived from the
ECMAScript Programming Language Standard. JSON defines a small set of
formatting rules for the portable representation of structured data.
This memo provides information for the Internet community.Date and Time on the Internet: TimestampsClearswift Corporation1310 WatersideArlington Business ParkThealeReadingRG7 4SAUK+44 11 8903 8903+44 11 8903 9000GK@ACM.ORGSun Microsystems1050 Lakes Drive, Suite 250West CovinaCA91790USAchris.newman@sun.com This document defines a date and time format for use in Internet
protocols that is a profile of the ISO 8601 standard for representation
of dates and times using the Gregorian calendar. Resource Records for the DNS Security ExtensionsThis document is part of a family of documents that describe the DNS
Security Extensions (DNSSEC). The DNS Security Extensions are a
collection of resource records and protocol modifications that provide
source authentication for the DNS. This document defines the public key
(DNSKEY), delegation signer (DS), resource record digital signature
(RRSIG), and authenticated denial of existence (NSEC) resource records.
The purpose and format of each resource record is described in detail,
and an example of each resource record is given. This document obsoletes RFC 2535 and incorporates changes from all
updates to RFC 2535. [STANDARDS-TRACK]Internet ProtocolUniversity of Southern California (USC)/Information Sciences
Institute4676 Admiralty WayMarina del ReyCA90291USA Recommendation for IPv6 Address Text RepresentationAs IPv6 deployment increases, there will be a dramatic increase in the need to use IPv6 addresses in text. While the IPv6 address architecture in Section 2.2 of RFC 4291 describes a flexible model for text representation of an IPv6 address, this flexibility has been causing problems for operators, system engineers, and users. This document defines a canonical textual representation format. It does not define a format for internal storage, such as within an application or database. It is expected that the canonical format will be followed by humans and systems when representing IPv6 addresses as text, but all implementations must accept and be able to handle any legitimate RFC 4291 format. [STANDARDS-TRACK]Codes for the representation of names of countries, 3rd
editionInternational Organization for
StandardizationTextual Representation of Autonomous System (AS) NumbersA textual representation for Autonomous System (AS) numbers is defined as the decimal value of the AS number. This textual representation is to be used by all documents, systems, and user interfaces referring to AS numbers. [STANDARDS-TRACK]Domain Name System (DNS) Case Insensitivity ClarificationDomain Name System (DNS) names are "case insensitive". This document explains exactly what that means and provides a clear specification of the rules. This clarification updates RFCs 1034, 1035, and 2181. [STANDARDS-TRACK]Uniform Resource Identifier (URI): Generic SyntaxWorld Wide Web ConsortiumMassachusetts Institute of Technology77 Massachusetts AvenueCambridgeMA02139USA+1-617-253-5702+1-617-258-5999timbl@w3.orghttp://www.w3.org/People/Berners-Lee/Day Software5251 California Ave., Suite 110IrvineCA92617USA+1-949-679-2960+1-949-679-2972fielding@gbiv.comhttp://roy.gbiv.com/Adobe Systems Incorporated345 Park AveSan JoseCA95110USA+1-408-536-3024LMM@acm.orghttp://larry.masinter.net/
Applications
uniform resource identifierURIURLURNWWWresource
A Uniform Resource Identifier (URI) is a compact sequence of characters
that identifies an abstract or physical resource. This specification
defines the generic URI syntax and a process for resolving URI references
that might be in relative form, along with guidelines and security
considerations for the use of URIs on the Internet.
The URI syntax defines a grammar that is a superset of all valid URIs,
allowing an implementation to parse the common components of a URI
reference without knowing the scheme-specific requirements of every
possible identifier. This specification does not define a generative
grammar for URIs; that task is performed by the individual
specifications of each URI scheme.
Internet Message FormatQualcomm Incorporated5775 Morehouse DriveSan DiegoCA92121-1714US+1 858 651 4478presnick@qualcomm.comhttp://www.qualcomm.com/~presnick/This document specifies the Internet
Message Format (IMF), a syntax for text messages
that are sent between computer users, within
the framework of "electronic mail"
messages. This specification is a revision of
Request For Comments (RFC) 2822, which
itself superseded Request For Comments (RFC)
822, "Standard for the Format of ARPA
Internet Text Messages", updating it to
reflect current practice and incorporating
incremental changes that were specified in
other RFCs.Hypertext Transfer Protocol -- HTTP/1.1Department of Information and Computer
ScienceUniversity of California, IrvineIrvineCA92697-3425+1(949)824-1715fielding@ics.uci.eduWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682jg@w3.orgCompaq Computer CorporationWestern Research Laboratory250 University AvenuePalo AltoCA94305mogul@wrl.dec.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682frystyk@w3.orgXerox CorporationMIT Laboratory for Computer Science, NE43-3563333 Coyote Hill RoadPalo AltoCA94034masinter@parc.xerox.comMicrosoft Corporation1 Microsoft WayRedmondWA98052paulle@microsoft.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682timbl@w3.org The Hypertext Transfer Protocol (HTTP) is an application-level protocol
for distributed, collaborative, hypermedia information systems. It is a
generic, stateless, protocol which can be used for many tasks beyond its
use for hypertext, such as name servers and distributed object
management systems, through extension of its request methods, error
codes and headers . A feature of HTTP is the typing and negotiation of
data representation, allowing systems to be built independently of the
data being transferred. HTTP has been in use by the World-Wide Web global information initiative
since 1990. This specification defines the protocol referred to as
"HTTP/1.1", and is an update to RFC 2068 . Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]
To overcome issues with misbehaving HTTP cache infrastructure, clients may use the
adhoc and improbably used query parameter with a random value of their choosing. As
instructs servers to ignore unknown parameters, this is unlikely to have any known side effects.
Use of an unknown parameter to overcome misbehaving caches is not part of any specification
and is offered here for informational purposes.
Things that need to be done to this draft.
authentication what?clean up must should, ref 2119?better language on data formats... it was just a rough startSecurity considerations?Is there a privacy considerations things we have to do now?