When Should You Separate a Domain Query from a Nameserver Query in RDAP?
The right RDAP starting point depends on the target of your question: a domain, one nameserver, or a set of search results.
When you see a nameserver name in an RDAP response, the next step is not always the same. Sometimes you only need to know which nameserver names are associated with a domain. Sometimes you need to focus on one particular nameserver. In another case, you may want to find domains associated with a nameserver or an IP address. These are three different questions, and they lead to different RDAP paths. When choosing an RDAP nameserver query, use the target of your question—not simply the fields visible in a response—as the practical test.
At a glance
- Domains and nameservers are separate RDAP object classes; first identify which object your question concerns.
- Start with a domain query to review nameserver names associated with a domain, and use a nameserver query when the question concerns one specific nameserver object.
- When you need multiple results based on a nameserver or IP address, use the relevant search endpoint rather than a direct object query.
- RDAP servers may not support every query type; an unsupported type must return HTTP 501.
First, separate the question into three targets
RDAP defines domains and nameservers as separate object classes. Both can be returned by Regional Internet Registries and Domain Name Registries. Before starting a query, it is therefore useful to state the question clearly: are you requesting information about a domain, reviewing one specific nameserver object, or looking for multiple records that match a criterion?
A nameserver object represents information about DNS nameservers used in forward and reverse DNS. However, registries can present nameserver information differently. Some expose it as an attribute of a domain name, while others model nameservers as first-class objects. The RDAP standard accommodates these models and variation between them.
The decision rule is simple: use the domain path for a question about a domain, the nameserver path for a question about a particular nameserver object, and a search path when you need to find multiple results. This prevents treating one response as a substitute for a different query target.
- Domain target: I need information about one domain.
- Single nameserver target: I need to review a particular nameserver object.
- Search target: I need to find results associated with a nameserver name or IP address.
Source: [2]
Start with the domain path for a domain question
If your question concerns a particular domain, a domain query is the appropriate starting point. In RDAP, the domain query form is domain/domain-name. The domain name must be fully qualified relative to the root. For example, when you query example.com, the target is the domain object.
Example scenario: for example.com, your purpose is to review which nameserver names appear in the domain response. Your question is still about example.com, so starting with domain/example.com matches the target. This example does not conclude that additional nameserver data is present or absent. It only shows that the question is directed at the domain object.
Keep another limit in mind when reading RDAP responses: members representing registration data can be absent. Servers may omit optional registration-data members according to their own policies. Do not treat a member that is absent from a response, by itself, as proof that no registration data exists. First decide whether your question still concerns the domain or has changed to a particular nameserver object.
- Domain query form: domain/domain-name
- The domain name must be fully qualified.
- Do not treat absent optional registration data as proof of nonexistence.
Split the query when the question becomes about one nameserver object
Use a nameserver query when your review target is a particular nameserver. The direct query form is nameserver/nameserver-name, and the nameserver name must be a fully qualified host name. This is primarily a change of target: you are now asking about the nameserver object rather than the domain.
A nameserver name appearing in a domain response may reflect a registry model that exposes nameserver information as a domain attribute. Other registries model nameservers as first-class objects. Because these models differ, do not interpret a name in a domain response as the result of a separate nameserver query. The narrower documented point is that registries can model nameserver information differently, and optional registration-data members can be absent from a response.
Example scenario: you see ns1.example.com in a domain/example.com response. If your question is, “Which nameserver name is associated with example.com?”, the domain query matches your target. If your question is, “What does RDAP return for the ns1.example.com nameserver object?”, the target has changed; use nameserver/ns1.example.com. This distinction does not claim that the domain response is incomplete or complete.
- Single nameserver query form: nameserver/nameserver-name
- The nameserver name must be a fully qualified host name.
- Do not treat a name in a domain response and a separate nameserver-object query as the same operation.
Use search endpoints when you need multiple results
You may start with a nameserver name and want to find domains delegated to it. In that case, the target is not one domain or one nameserver object; it is a domain search. RDAP defines the form domains?nsLdhName= for this purpose.
If you start with an IP address and want to find domains delegated to nameservers that resolve to that IP address, use domains?nsIp=. This path also asks for a set of domain results.
RDAP defines two separate paths for searching nameserver objects: nameservers?name= by name and nameservers?ip= by IP address. Keep these distinct from a direct nameserver/nameserver-name query. The former are searches; the latter is a direct object query for one nameserver name.
- Domain search by nameserver name: domains?nsLdhName=
- Domain search by nameservers resolving to an IP address: domains?nsIp=
- Nameserver search by name: nameservers?name=
- Nameserver search by IP address: nameservers?ip=
Source: [1]
Read HTTP 501 together with the query target
RDAP servers may support only a subset of features according to local requirements. Therefore, wanting to use a defined search endpoint does not mean that every RDAP server provides it.
A server must return HTTP 501 Not Implemented for an unsupported query type. If you receive this response, first check whether you classified the target correctly: is it a domain, one nameserver, or a search? Then consider whether another supported query form matches the same question. A 501 response is a reminder not to assume that every defined feature is available on every server.
- HTTP 501 indicates an unsupported query type.
- Classify the target again: domain, one nameserver, or search.
- Allow for the server supporting only a subset of features.
Source: [1]
Practical checklist
- Classify your question as a domain, single-nameserver, or search target.
- Use domain/domain-name to review a domain.
- Use nameserver/fully-qualified-nameserver-name for a specific nameserver object.
- Do not treat an absent optional member as proof that no registration data exists.
- Consider domains?nsLdhName= to search for domains by nameserver name.
- When starting with an IP address, choose the appropriate nsIp or ip search path.
- When you receive HTTP 501, allow for the server not supporting that query type.
The safest way to separate domain and nameserver queries in RDAP is to classify the question by its object target rather than drawing conclusions from fields that appear or do not appear in a response. Start with domain/domain-name for a domain. Use nameserver/nameserver-name when the question becomes about one nameserver object. If you need multiple results from a nameserver name or IP address, choose the relevant domains or nameservers search path. Also allow for optional response members to be omitted and for some query types not to be supported.
Frequently asked questions
Which query should I use when a domain response shows a nameserver name?
If your question is which nameserver name is associated with the domain, start with domain/domain-name. If your question concerns a particular nameserver object, use nameserver/nameserver-name. Domains and nameservers are separate RDAP object classes.
How can I search for domains by nameserver name in RDAP?
The domain search form by nameserver name is domains?nsLdhName=. It is intended to find domains delegated to that nameserver. If the server does not support this query type, it must return HTTP 501.
What does HTTP 501 mean in RDAP?
HTTP 501 Not Implemented indicates that the server does not support the relevant query type. RDAP servers may support only a subset of features according to local requirements.
Sources
[1] rfc9082.txt
[2] rfc9083.txt
