By RDAPLookup Editorial TeamPublished September 7, 2026 · Last reviewed September 8, 2026

Moving from WHOIS to RDAP: A Practical Migration Guide

Migrating from WHOIS to RDAP involves more than replacing a port 43 connection with an HTTPS request. This guide covers discovery, querying, parsing, errors, fallbacks and production testing.

If an application still connects to a WHOIS service on port 43 and extracts values from plain text, it is time to plan its migration to the Registration Data Access Protocol (RDAP).

For generic top-level domains, the transition has already reached an important milestone. On 28 January 2025, RDAP became the definitive source for registration data provided by ICANN-accredited registrars and generic top-level domain registries. Those contracted parties are no longer required to maintain their former WHOIS services.

That does not mean WHOIS disappeared everywhere on that date. Some operators continue to provide it voluntarily, and country-code top-level domains establish their own policies. Many ccTLDs still offer WHOIS only, while others operate RDAP services that are not included in the official IANA bootstrap registry. See the current RDAP deployment status across ccTLDs for a breakdown of that variation.

Moving from WHOIS to RDAP is therefore not simply a matter of changing the destination port. A reliable migration must account for service discovery, structured responses, HTTP behavior, privacy policies, rate limits and uneven deployment across TLDs.

Scope note: The 28 January 2025 WHOIS sunset concerned contractual requirements for ICANN-contracted gTLD registries and registrars. It did not require every ccTLD to stop offering WHOIS.

Why WHOIS integrations need to change

WHOIS was designed long before modern web APIs. A client normally opens a TCP connection to port 43, submits a text query and receives an unstructured text response.

Although the interaction is simple, the output is not standardized enough for dependable automation. Field names, date formats, character encodings, referral behavior and rate-limit messages can differ between operators. Parsers often accumulate registry-specific regular expressions and special cases over time.

RDAP addresses those limitations by using HTTPS and structured JSON. It defines standard query paths, response objects, error formats and service-discovery mechanisms. It also supports internationalized data, redirection, authentication and differentiated access.

Area	WHOIS	RDAP
Transport	TCP, normally port 43	HTTPS
Response format	Plain text	Structured JSON
Service discovery	Often manually configured	IANA bootstrap registries
Errors	Usually text messages	HTTP status codes and RDAP error objects
Internationalization	Inconsistent	Defined support for internationalized data
Access control	Limited protocol support	Can use HTTP authentication and authorization
Extensibility	Operator-specific text	Declared RDAP extensions

See the difference yourself: Run a domain through the RDAP lookup tool and inspect the structured registration data returned by its authoritative endpoint.

The important operational improvement is not merely that JSON is easier to parse. RDAP gives clients a defined model for understanding what a response represents and how it was obtained.

Who should migrate?

You should audit your systems if they perform any automated registration-data lookup, including:

domain-expiration monitoring;
registrar identification;
domain-status or transfer-lock checks;
cybersecurity enrichment;
abuse investigation;
brand or portfolio monitoring;
nameserver tracking;
IP address or ASN registration lookups;
domain inventory and compliance checks.

Do not limit the audit to application code. WHOIS calls may also exist in shell scripts, scheduled tasks, monitoring plugins, data pipelines, support tools and third-party integrations.

A safe WHOIS-to-RDAP migration process

1. Inventory what the existing integration actually uses

Start by documenting the outputs your system consumes rather than attempting to reproduce the entire WHOIS response.

For each integration, record:

the resource being queried: domain, IP address or Autonomous System number;
the WHOIS service or referral mechanism currently used;
the fields extracted from the response;
registry-specific parsing rules;
retry, timeout and caching behavior;
downstream decisions based on the data;
assumptions about fields always being present;
any fallback data sources.

This exercise often reveals that an application needs only a small subset of registration data, such as the registrar, expiration event, nameservers and domain status values. Defining that normalized internal model first makes the RDAP parser considerably easier to design.

For a practical reference while mapping status values, see the RDAP status guide, which explains common EPP-to-RDAP mappings, lifecycle states, locks and when a registrant may need to act.

It also exposes dangerous assumptions. For example, an expiration date is frequently available, but a client should not assume that every registry will return one or that every date-looking event has the same meaning.

2. Replace hard-coded servers with RDAP service discovery

A client cannot reliably construct an RDAP endpoint by adding rdap. in front of a TLD. It needs to discover the appropriate base URL.

For domain names, the standard starting point is the IANA Bootstrap Service Registry for the Domain Name Space. Its machine-readable dns.json file maps TLD labels to one or more RDAP base URLs. Separate IANA bootstrap registries cover IPv4, IPv6 and Autonomous System numbers.

A domain discovery process should:

normalize the domain name;
convert an internationalized TLD to its ASCII A-label when necessary;
extract the TLD;
find that TLD in the current bootstrap data;
select a listed HTTPS base URL;
append the appropriate RDAP query path.

Cache the bootstrap data locally instead of downloading it for every lookup. Refresh it on a controlled schedule and retain the last valid copy if a refresh fails. Treat invalid JSON, an unexpectedly empty registry or a network error as a refresh failure—not as evidence that every endpoint has disappeared.

The IANA bootstrap is the standards-based source for discovery, but its coverage does not equal total real-world deployment. An allocated TLD is not guaranteed to have a bootstrap entry, and some ccTLD operators expose working RDAP endpoints without registering them there. Our current RDAP deployment status by TLD separates IANA-listed services from independently discovered endpoints and WHOIS-only TLDs.

If you maintain a supplemental endpoint list, keep its provenance, last verification date and validation result. It should augment IANA discovery, not silently replace it.

3. Construct the correct query

RDAP uses resource-specific path segments. The most common exact-match query types are:

Resource	Query path pattern
Domain name	`domain/{domain-name}`
IP address or network	`ip/{address-or-prefix}`
Autonomous System number	`autnum/{number}`
Nameserver	`nameserver/{nameserver-name}`
Entity	`entity/{handle}`
Service information	`help`

For example, a domain lookup combines the discovered base URL with domain/ followed by the fully qualified domain name. Do not discard a path already present in the base URL, and resolve the final URL according to normal URI rules.

Use GET when retrieving an RDAP response. A client should indicate that it accepts application/rdap+json; supporting ordinary JSON as a secondary accepted media type can improve interoperability.

Domain, IP and ASN queries do not necessarily use the same service. Route each resource type through its corresponding bootstrap registry rather than sending every query to a domain-registration endpoint.

4. Treat HTTP behavior as part of the protocol

WHOIS clients frequently interpret every returned line as data. RDAP clients must first interpret the HTTP response.

HTTP response	Typical meaning for an RDAP client
`200 OK`	A response was returned and should be validated and parsed.
`301`, `302`, `303` or `307`	Follow the URL supplied in the `Location` header, subject to a safe redirect limit.
`400 Bad Request`	The query could not be interpreted. Do not retry it unchanged.
`401 Unauthorized`	Authentication is required.
`403 Forbidden`	The service understood the request but policy prevents access.
`404 Not Found`	No result was found for that query at the authoritative service.
`429 Too Many Requests`	Reduce the request rate and honor `Retry-After` when supplied.
`5xx`	The service experienced a temporary server-side failure.
`501 Not Implemented`	That query type is not supported by the service.

Do not translate all non-200 responses into “domain available.” A 404 received after correct authoritative routing can represent a negative lookup result, but availability is a registry business decision and should not be inferred from an arbitrary network failure, malformed query or incorrect endpoint.

Use separate retry policies for separate failure classes. A timeout or 5xx response may justify a bounded retry with backoff. A 400 generally will not. A 429 requires slower requests and should follow the operator’s instructions.

5. Validate that the response is actually RDAP

Receiving JSON is not sufficient. A proxy, security product or unrelated API can also return valid JSON.

At minimum, validate:

the HTTP status and response media type;
that the top-level object contains rdapConformance;
that the returned object type matches the query;
that objectClassName is appropriate, such as domain for a domain lookup;
that ldhName or unicodeName corresponds to the requested domain;
that required values have the expected JSON types;
that redirects have not exceeded a safe limit.

The rdapConformance array identifies the specifications and extensions used to construct the response. A client should understand the fields it supports and tolerate unknown extension fields instead of rejecting the entire response.

6. Parse meaning, not visual position

RDAP responses are structured, but many values are represented as arrays because more than one entity, event, status or link can be present. Their order should not be treated as business meaning.

Important domain-response members include:

ldhName and, where applicable, unicodeName;
status for registration status values;
events for registration, expiration, transfer and last-change events;
entities for registrars, registrants and other contacts;
nameservers;
secureDNS for DNSSEC-related registration information;
notices and remarks for service and object-specific qualifications;
links for self, related and alternate resources;
rdapConformance for the applicable specifications and extensions.

Select an event by its eventAction, not by assuming that the first date is the registration date or that the last date is expiration. Select entities by their roles, not by their position in the array.

Contact information may be represented using vcardArray, a JSON form of vCard known as jCard. A robust parser needs to traverse its property arrays and recognize their names and parameters. It should not depend on a fixed number or order of contact fields.

Finally, preserve notices and remarks. They can explain redaction, terms of use, truncation, authorization requirements or other limitations that materially affect how the response should be interpreted.

7. Do not expect a one-to-one WHOIS field mapping

A common migration mistake is to recreate the old WHOIS text schema and force every RDAP response into it. Some mappings are straightforward, but others depend on roles, event actions or registry policy.

Existing requirement	RDAP interpretation
Domain name	`ldhName` and optionally `unicodeName`
Registrar	An entity containing the `registrar` role
Creation date	An event with the appropriate registration action
Expiration date	An event with the appropriate expiration action, when supplied
Updated date	A last-changed event, when supplied
Domain statuses	Values in the `status` array
Nameservers	Objects in the `nameservers` array
Registrant details	An entity with the `registrant` role, subject to disclosure policy

Model missing, redacted and unavailable values separately. An absent registrant name is not the same condition as a failed request. Likewise, a successfully parsed response without an expiration event should not be converted into an invented or stale date.

8. Follow redirects and referrals carefully

RDAP can direct a client to another source in two ways:

an HTTP redirect with a Location header; or
a link within the RDAP response, identified by its relationship type.

Follow HTTP redirects using standard HTTP behavior and enforce limits to prevent loops. Validate each destination and require HTTPS for remote requests.

Links inside a response should be processed according to their declared relationship. Do not recursively follow every URL. Doing so can produce loops, duplicate records or requests to unrelated human-readable policy pages.

Where both registry and registrar data are available, record their provenance rather than silently merging conflicting values. A downstream user should be able to tell which service supplied a value.

9. Design for privacy and differentiated access

RDAP standardizes how registration data is requested and represented; it does not guarantee that every field is public.

A public response may omit or redact personal data. A service may return different information to authenticated users with an appropriate authorization level. Policies also vary between registries, registrars and jurisdictions.

Your application should therefore:

distinguish redacted data from parser errors;
preserve redaction explanations in notices, remarks or related fields;
avoid assuming that authentication guarantees access to a particular field;
protect any credentials used for nonpublic access;
apply retention and access controls to retrieved personal data;
avoid logging complete responses unless operationally necessary.

RDAP can support differentiated access, but authorization policy is determined by the service operator and applicable registration-data rules.

10. Implement rate limiting, caching and observability

Moving to HTTPS does not make registration data an unlimited API. Operators can enforce different thresholds and may adjust them without notice.

Use:

a descriptive user agent and contact information where appropriate;
per-service rather than only global rate limits;
bounded concurrency;
exponential backoff with jitter for temporary failures;
Retry-After handling for 429 responses;
caching consistent with HTTP response headers and your freshness requirements;
request metrics separated by endpoint and response category.

Monitor discovery failures, timeouts, redirects, invalid responses, rate limits and missing business-critical fields separately. A single generic “RDAP failed” counter will not tell you whether the problem is your parser, your routing data or the remote service.

Browser-based applications require one additional consideration: cross-origin resource sharing. RDAP services are recommended to return a suitable Access-Control-Allow-Origin header for public resources, but implementations are not perfectly uniform. A request that succeeds from a backend may still be blocked by the browser’s same-origin policy. If consistent browser support is required, test CORS per endpoint or perform the request through a controlled backend.

11. Define a deliberate WHOIS fallback policy

For ICANN-contracted gTLDs, RDAP should be the primary registration-data source. For ccTLDs, actual deployment is more varied.

A transitional system may still need WHOIS fallback, but fallback should be explicit and observable. Define:

which TLDs are eligible for fallback;
which RDAP failures can trigger it;
how long fallback data may be cached;
how the resulting source is labeled;
whether your use complies with the operator’s terms and rate limits;
when the fallback will be reviewed or removed.

Do not fall back to WHOIS merely because a public RDAP response contains less personal information. That is a disclosure-policy outcome, not a transport failure.

For current coverage, consult the RDAP availability and deployment table. Because endpoint status can change, avoid embedding an old copy of the coverage list permanently in application code.

How to test the migration

A migration should be tested against multiple operators and response shapes, not only a single .com domain.

Build a test set containing:

registered and unregistered domains;
several gTLDs and ccTLDs;
an internationalized domain name;
a domain with multiple statuses;
responses with missing or redacted contact data;
a registry-to-registrar referral or redirect;
an endpoint that rate-limits repeated requests;
temporary server and network failures;
IP address and ASN queries if your system supports them;
responses containing extensions unknown to your parser.

Use the RDAP lookup tool to inspect human-readable results while building expected test cases, but keep automated assertions focused on protocol semantics rather than a particular visual presentation.

Run WHOIS and RDAP in parallel before switching

For an established production system, begin with a shadow period:

keep the existing output active;
query RDAP in parallel for an agreed sample;
normalize both sources into comparable internal fields;
measure missing values and genuine disagreements;
inspect differences by TLD and operator;
correct parsing and routing assumptions;
move consumers to RDAP gradually;
retain WHOIS only where a documented fallback remains necessary.

Do not expect text equality. The useful comparison is whether each source supports the business decision your system needs to make.

Production migration checklist

Common migration mistakes

Assuming every TLD has an IANA-listed RDAP endpoint

The IANA bootstrap is the correct standards-based starting point, but an entry is not guaranteed for every allocated TLD. Coverage gaps are particularly relevant when supporting ccTLDs.

Treating every 404 as domain availability

A negative RDAP result is only meaningful when the query was valid and reached the correct authoritative service. Even then, registration availability may depend on reservation, eligibility and registry-policy rules outside RDAP.

Depending on array order

Events, entities, statuses and links must be interpreted using their semantic labels. Their visual or serialized order is not a stable interface.

Rejecting responses with unfamiliar fields

RDAP is extensible. Validate the core fields you require, recognize declared extensions you support and tolerate additional data.

Treating redacted data as a broken response

RDAP does not override privacy and disclosure rules. A technically valid response may intentionally omit information available in old datasets or to differently authorized users.

Assuming RDAP validates DNSSEC

An RDAP domain response can expose DNSSEC-related registration information through secureDNS. It does not independently validate the domain’s complete DNSSEC chain. DNSSEC validation requires DNS queries and cryptographic verification.

Frequently asked questions

Is WHOIS completely gone?

No. RDAP became the definitive registration-data service for ICANN-contracted gTLD registries and registrars on 28 January 2025, and those parties are no longer required to provide their former WHOIS services. Some still do, and ccTLD operators follow their own policies.

Does every domain extension support RDAP?

No. Deployment remains uneven among ccTLDs. Some are listed in the IANA bootstrap, some appear to operate independently discovered RDAP endpoints, and others still provide WHOIS without a public RDAP service.

Does RDAP always return an expiration date?

No. When an expiration event is present, it can be parsed consistently by its action. However, the information returned still depends on the registry, registrar, object and applicable policy. Clients must support a missing value.

Does RDAP expose more personal information than WHOIS?

Not necessarily. RDAP provides a structured model and can support differentiated access, but it does not determine which registration data must be public. Public responses can contain redacted or omitted personal information.

Can a frontend application query RDAP endpoints directly?

Sometimes. Public RDAP services are encouraged to support CORS, but behavior varies. Test the relevant endpoints. A backend integration provides more consistent control over redirects, caching, rate limiting and failure handling.

Should a new application implement WHOIS as well as RDAP?

For gTLD registration data, build around RDAP. Add WHOIS only when your supported ccTLD coverage requires it and you can maintain a clearly defined fallback. Avoid making new application logic depend primarily on unstructured WHOIS output.

Final thoughts

RDAP replaces the weakest parts of WHOIS with standardized discovery, HTTPS, structured responses and explicit error behavior. Those improvements make registration data easier to integrate, but they do not remove operational complexity.

The most reliable migration starts with a clear internal data model, discovers authoritative services instead of guessing endpoints, validates responses before parsing them and treats privacy, deployment gaps and rate limits as normal conditions. Migrate the decision-making logic—not just the network request—and your integration will be much easier to maintain as WHOIS availability continues to decline.