One document matched: draft-ietf-weirds-using-http-01.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd"
[
<!ENTITY RFC2119 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY RFC2616 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>
<!ENTITY RFC3986 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY RFC4627 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>
<!ENTITY RFC5234 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml'>
]>
<?rfc toc="true"?>
<rfc category="std" docName="draft-ietf-weirds-using-http-01" ipr="trust200902">
<front>
<title abbrev="RDAP over HTTP">
Using the Registration Data Access Protocol (RDAP) with HTTP
</title>
<author fullname="Andrew Lee Newton" initials="A.L." surname="Newton">
<organization abbrev="ARIN">American Registry for Internet Numbers</organization>
<address>
<postal>
<street>3635 Concorde Parkway</street>
<city>Chantilly</city>
<region>VA</region>
<country>US</country>
<code>20151</code>
</postal>
<email>andy@arin.net</email>
<uri>http://www.arin.net</uri>
</address>
</author>
<author fullname="Byron J. Ellacott" initials="B.J." surname="Ellacott">
<organization abbrev="APNIC">Asia Pacific Network Information Center</organization>
<address>
<postal>
<street>6 Cordelia Street</street>
<city>South Brisbane</city>
<country>Australia</country>
<code>QLD 4101</code>
</postal>
<email>bje@apnic.net</email>
<uri>http://www.apnic.net</uri>
</address>
</author>
<author initials="N." surname="Kong" fullname="Ning Kong">
<organization abbrev="CNNIC">
China Internet Network Information Center
</organization>
<address>
<postal>
<street>4 South 4th Street, Zhongguancun, Haidian District </street>
<country>China</country>
<code>100190</code> <city>Beijing</city>
</postal>
<phone>+86 10 5881 3147</phone>
<email>nkong@cnnic.cn</email>
</address>
</author>
<date/>
<abstract>
<t> This document describes the usage of the Registration Data Access Protocol (RDAP)
using HTTP.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
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.
</t>
<t>
In designing these common usage patterns, this draft endeavours to satisfy
requirements for a Registration Data Access Protocol (RDAP) that is documented in
<xref target="draft-kucherawy-weirds-requirements"/>. 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 implementation should be possible using common
operating system scripting tools.
</t>
<t>
This is the basic usage pattern for this protocol:
<list style="numbers">
<t>A client issues an HTTP query using GET. As an example, a query for
the network registration 192.0.2.0 might be http://example.com/ip/192.0.2.0.</t>
<t>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.</t>
<t>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 Location: header containing an HTTP URL pointing
to the information or another server known to have knowledge of the location of
the information. The client is expected to re-query using that HTTP URL.</t>
<t>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.</t>
</list>
</t>
<t>
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.
</t>
</section>
<section title="Terminology">
<t>
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 <xref target="RFC2119"/>.
</t>
<t>
As is noted in <xref target="SAC-051">SSAC Report on WHOIS Terminology and Structure</xref>,
the term "Whois" is overloaded, often referring to a protocol, a service and data.
In accordance with <xref target="SAC-051"></xref>, this document describes the base
behavior for a Registration Data Access Protocol (RDAP).
<xref target="SAC-051"></xref> describes a protocol profile of RDAP for Doman Name
Registries (DNRs), DNRD-AP. This document and others from the IETF WEIRDS working
group describe a single protocol, RDAP, for access to the data of both DNRs and
Regional Internet Registries (RIRs). RIRs are also often referred to as number resource
registries and are responsible for the registration of IP address networks and
autonomous system numbers.
</t>
</section>
<section title="Design Intents">
<t>
There are a few design criteria this document attempts to support.
</t>
<t>
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 <xref target="RFC2616">HTTP</xref>.
Should a result contain more than one result,
some of which are better served by other servers, the redirection model becomes
much more complicated.
</t>
<t>
Second, multiple response formats are supported by this protocol. At present the
IETF WEIRDS working group is defining only a <xref target="RFC4627">JSON</xref>
response format, but server operators
may use other data formats when those formats are requested.
</t>
<t> 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.
</t>
</section>
<section title="Queries">
<section title="Accept Header" anchor="accept_header">
<t> Clients SHOULD put the media type of the format they desire in
the Accept header field.
<list style="empty">
<t>Accept: application/rdap</t>
</list>
</t>
<t>
Servers SHOULD respond with an appropriate media type
in the Content-Type header in accordance with the preference rules for the Accept
header in <xref target="RFC2616">HTTP</xref>.
<list style="empty">
<t>Content-Type: application/rdap</t>
</list>
</t>
<t>
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 (e.g. "application/rdap").
In other words, a client may use "application/json" to express that it
desires JSON or "application/rdap" to express that it
desires RDAP specific JSON, but the server would respond with
"application/rdap".
</t>
</section>
<section title="Query Parameters" anchor="parameters">
<t>
Servers SHOULD ignore unknown query parameters. Use of unknown query
parameters for cache-busting is described in <xref target="cache-busting"></xref>.
</t>
</section>
</section>
<section title="Types of HTTP Response" anchor="http_responses">
<t>
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.
</t>
<section title="Positive Answers">
<t>
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.
</t>
</section>
<section title="Redirects">
<t>
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 Location: 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.
</t>
<t>
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 top level domain (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).
</t>
</section>
<section title="Negative Answers">
<t>
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 negative answer in the HTTP entity body.
</t>
</section>
<section title="Malformed Queries">
<t>
If a server receives a query which it cannot understand, it SHOULD return
a 400 response code. Optionally, it MAY include additional information regarding
this negative answer in the HTTP entity body.
</t>
</section>
</section>
<section title="Extensibility" anchor="extensibility">
<t>
For extensibility purposes, this document defines an IANA registry for prefixes
used in <xref target="RFC4627">JSON</xref> data serialization and URI path
segments (see <xref target="iana_considerations"></xref>).
</t>
<t>
Prefixes and identifiers 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 production of JSON names in <xref target="RFC5234">ABNF</xref>.</t>
<figure anchor="json_name_abnf">
<preamble>
ABNF for JSON names
</preamble>
<artwork>
name = ALPHA *( ALPHA / DIGIT / "_" )
</artwork>
</figure>
<t> 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.
Second, a clean mapping between JSON and XML is easy to accomplish using these
rules.
</t>
</section>
<section title="IANA Considerations" anchor="iana_considerations">
<t>
This specification proposes an IANA registry for RDAP extensions. The
purpose of this registry is to ensure uniqueness of extension identifiers.
The extension identifier is used as prefix in JSON names and as a prefix
of path segments in RDAP URLs.
</t>
<t>
The production rule for these identifiers is specified in <xref target="extensibility"/>.
</t>
<t>
In accordance with RFC5226, the IANA policy for assigning new values shall
be Specification Required: values and their meanings must be documented in
an RFC or in some other permanent and readily available reference, in
sufficient detail that interoperability between independent implementations
is possible.
</t>
<t>
The following is a preliminary template for an RDAP extension registration:
<list style="empty">
<t>Extension identifier: the identifier of the extension</t>
<t>Registry operator: the name of the registry operator</t>
<t>Published specification: RFC number, bibliographical reference or URL
to a permanent and readily available specification</t>
<t>Person & email address to contact for further information:
The names and email addresses of individuals for contact regarding this registry entry
</t>
<t>Intended usage: brief reasons for this registry entry</t>
</list>
</t>
<t>
The following is an example of a registration in the RDAP extension registry:
<list style="empty">
<t>Extension identifier: lunarNic</t>
<t>Registry operator: The Registry of the Moon, LLC</t>
<t>Published specification: http://www.example/moon_apis/rdap</t>
<t>Person & email address to contact for further information:
Professor Bernardo de la Paz <berny@moon.example>
</t>
<t>Intended usage: COMMON</t>
</list>
</t>
</section>
<section title="Internationalization Considerations">
<section title="URIs and IRIs">
<t>
Clients MAY use IRIs as they see fit, but MUST transform them to
<xref target="RFC3986">URIs</xref> for interaction with RDAP servers.
RDAP servers MUST use URIs in all responses, and clients MAY transform
these URIs to IRIs.
</t>
</section>
<section title="Language Identifiers in Queries and Responses"
anchor="language_identifiers_in_queries_and_responses">
<t>
Depending on the data format of the response, servers MAY include
data in character sets other than ASCII and languages other than
English (the data format will most likely be in Unicode and almost
certainly languages other than English will be encountered).
Under most scenarios, clients requesting data will not signal
that the data be returned in a particular language or script.
On the other hand, when servers return data and have knowledge
that the data is in a language or script, the data should be
annotated with language identifiers thus allowing clients to process
and display the data accordingly.
</t>
<t>
A language identifier in the response is specified in section 5.3 of
<xref target="draft-ietf-weirds-json-response"></xref>. It is used to indicate the
language/script of the response data. It is possible that registration
data is stored in several different languages and returned in a single
response. Data portion of different language types SHOULD be tagged with
its corresponding identifier if known.
</t>
</section>
<section title="Language Identifiers in HTTP Headers" anchor="language_identifiers_in_http_headers">
<t>
Given the description of the use of language identifiers in
<xref target="language_identifiers_in_queries_and_responses"></xref>,
unless otherwise specified servers SHOULD ignore the
<xref target="RFC2616">HTTP</xref> Accept-Language header when
formulating responses.
</t>
<t>
However, servers MAY return language identifiers in the
Content-Language header so as to inform clients of the
intended language of HTTP layer messages.
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="draft-kucherawy-weirds-requirements">
<front>
<title>Requirements For Internet Registry Services</title>
<author initials="M." surname="Kucherawy" fullname="M. Kucherawy">
<organization>Cloudmark</organization>
</author>
<date day="2" month="April" year="2011"/>
</front>
<seriesInfo name="Work in progress: Internet Drafts"
value="draft-kucherawy-weirds-requirements-04.txt"/>
</reference>
<reference anchor="draft-ietf-weirds-json-response">
<front>
<title>JSON Responses for the Registration Data Access Protocol (RDAP)</title>
<author fullname="Andrew Lee Newton" initials="A.L." surname="Newton">
<organization abbrev="ARIN">American Registry for Internet Numbers</organization>
<address>
<postal>
<street>3635 Concorde Parkway</street>
<city>Chantilly</city>
<region>VA</region>
<country>US</country>
<code>20151</code>
</postal>
<email>andy@arin.net</email>
<uri>http://www.arin.net</uri>
</address>
</author>
<author initials="S." surname="Hollenbeck" fullname="Scott Hollenbeck">
<organization>Verisign Labs</organization>
<address>
<postal>
<street>12061 Bluemont Way</street>
<city>Reston</city>
<region>VA</region>
<code>20190</code>
<country>US</country>
</postal>
<email>shollenbeck@verisign.com</email>
<uri>http://www.verisignlabs.com/</uri>
</address>
</author>
<date day="4" month="December" year="2012"/>
</front>
<seriesInfo name="Work in progress: Internet Drafts"
value="draft-ietf-weirds-json-response-01.txt"/>
</reference>
<reference anchor="SAC-051">
<front>
<title>SSAC Report on Domain Name WHOIS Terminology and Structure</title>
<author initials="D." surname="Piscitello" role="editor" />
<date day="19" month="September" year="2011"/>
</front>
</reference>
&RFC2119;
&RFC4627;
&RFC3986;
&RFC2616;
&RFC5234;
</references>
<section title="Cache Busting" anchor="cache-busting">
<t>
To overcome issues with misbehaving <xref target="RFC2616">HTTP</xref> cache infrastructure, clients MAY use an
adhoc and improbably used query parameter with a random value of their choosing. As <xref target="parameters"></xref>
instructs servers to ignore unknown parameters, this is unlikely to have any known side effects.
</t>
<figure>
<preamble>
An example of using an unknown query parameter to bust caches:
</preamble>
<artwork>
http://example.com/ip/192.0.2.0?__fuhgetaboutit=xyz123
</artwork>
</figure>
<t>
Use of an unknown parameter to overcome misbehaving caches is not part of any specification
and is offered here for informational purposes.
</t>
</section>
<section title="Changelog">
<t>
<list style="hanging">
<t hangText="Initial WG -00:">Updated to working group document 2012-September-20</t>
<t hangText="-01">
<list style="symbols">
<t>Updated for the sections moved to the JSON responses draft.</t>
<t>Simplified media type, removed "level" parameter.</t>
<t>Updated 2119 language and added boilerplate.</t>
<t>In section 1, noted that redirects can go to redirect servers as well.</t>
<t>Added <xref target="language_identifiers_in_queries_and_responses"></xref>
and <xref target="language_identifiers_in_http_headers"></xref>.</t>
</list>
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 00:49:54 |