Efficient RDAP Referrals

Introduction Many Registration Data Access Protocol (RDAP, described in , , , and others) resources contain links to related RDAP resources. For example, in the domain space, an RDAP record for a domain name received from the registry operator may include a link for the RDAP record for the same object provided by the sponsoring registrar (for example, see ), while in the IP address space, an RDAP record for an address allocation may include links to enclosing or sibling prefixes. In both cases, RDAP service users are often equally if not more interested in these related RDAP resources than the resource provided by the TLD registry or RIR. While RDAP supports redirection of RDAP requests using HTTP redirections (which use a 3xx HTTP status and the "Location" header field, see Section 15.4 of ), it is not possible for RDAP servers to know a priori whether a client requesting an RDAP record is doing so because it wants to retrieve a related RDAP record, or its own, so it can only respond by providing the full RDAP response. The client must then parse that response in order to extract the relevant URL from the "links" property of the object. This results in the wasteful expenditure of time, compute resources and bandwidth on the part of both the client and server. This document describes an extension to RDAP that allows clients to request that an RDAP server refer them to the URL of a related resource.

RDAP Referral Request To request a referral to a related resource, the client sends an HTTP GET request to the RDAP server with a path of the form: referrals0_ref/ ]]> The client replaces <base path> with the path component of the RDAP server's base URL (which, as per , has a trailing / character), <lookup path> with the lookup path of the object being sought, and <relation> with the desired relationship type. For example, the path of a referral query for the domain example.com sent to an RDAP server whose base path is / would be: The referral query for the parent network of 192.0.2.42 would have the following full path: Lookup paths for domain names, IP networks, autonomous system numbers, nameservers, and entities are described in . Lookups defined by RDAP extensions may also use this extension. Referral requests for searches, where more than one object is returned, and help queries, as described by , are not supported. Servers MUST return an HTTP 400 for these requests.

RDAP Referral Response If the object specified in the request exists, a single appropriate link exists, and the client is authorised to perform the request, the server response MUST:

have an HTTP status code of 301 (Moved Permanently), 302 (Found), 303 (See Other), or 307 (Temporary Redirect); and
include an HTTP Location header field, whose value contains the URL of the linked resource.

If the server cannot find an appropriate link, the response MUST have an HTTP status of 404. If an RDAP server holds in its datastore more than one relationship type for an object, a scenario that is possible but not common, only one of the URLs, as determined by server policy, can be returned. The following examples use the HTTP/1.1 message exchange syntax as seen in . An example of a referral request from a domain registry to a domain registrar: An example of a referral request for a parent IPv4 network: An example of a referral request for a parent IPv6 network:

Selecting The Appropriate Link When the server receives a referral request, it must select which of an object's links it should use to construct the response. The rel property of the selected link MUST match <relation> path segment of the request. The type and hreflang properties of the link, if present, MUST match the Accept and (if specified) Accept-Language header fields of the request.

Caching by Intermediaries To facilitate caching of RDAP resources by intermediary proxies, servers which provide a referral based on the value of the Accept header field in the request MUST include a Vary header field (See Section 12.5.5 of ) in the response. This field MUST include accept, and MAY include other header field names. Example:

Client Processing of Referral Responses Note that as per Section 10.2.2 of [!@RFC9110], the URI-reference in location header fields MAY be relative. For relative references, RDAP clients MUST compute the full URI using the request URI.

RDAP Conformance Servers which implement this specification MUST include the string "referrals0" in the "rdapConformance" array in all RDAP responses.

IANA Considerations IANA is requested to register the following value in the RDAP Extensions Registry: Extension identifier: referrals0 Registry operator: any. Published specification: this document. Contact: the authors of this document. Intended usage: this extension allows clients to request to be referred to a related resource for an RDAP resource.

Security Considerations A malicious HTTP redirect has the potential to create an infinite loop, which can exhaust resources on both client and server side. To prevent such loops, RDAP servers which receive referral requests for the self relation MUST respond with a 400 HTTP status. As described in Section 15.4 of [!@RFC9110], when processing server responses, RDAP clients SHOULD detect and intervene in cyclical redirections.

Change Log This section is to be removed before publishing as an RFC.

Changes from 01 to 02

Add reference to which describes how gTLD RDAP servers link to registrar RDAP resoures.
Include <base path> in the path specification, and remove the / between <relation> and <lookup path> so that naive URL construction works.
Reuse the language from RFC 7480 on HTTP status codes used for redirection.
Fix HTTP status code in the examples.
Described the risk of redirection loops and things clients and servers have to do.

Changes from 00 to 01

Switch to using a path segment and a 30x redirect.
Describe how the server behaves when multiple links exist.

Changes from draft-brown-rdap-referrals-02 to draft-ietf-regext-rdap-referrals-00

Nothing apart from the name.

Changes from 01 to 02

add this change log.

Changes from 00 to 01

change extension identifer from registrar_link_header to referrals0.