RDAP

A minimal Ruby client to query RDAP APIs though a bootstrap server. No dependencies, no caching or bootstrap file (the query is routed through a bootstrap server first).

RDAP is a new protocol destined to replace WHOIS to query informations about domains, IPs, ASNs, etc. Not all TLDs support RDAP at the moment, but the deployment is going well: https://deployment.rdap.org

This library is optimal for low volume queries (the bootstrap server we used here enforces some throttling). If you need to perform a lot of queries, you should either:

avoid bootstrap servers and use a caching client like nicinfo
or run your own bootstrap server.

Installation

Add this line to your application's Gemfile:

gem 'rdap'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install rdap

Usage

You can use bin/console from this repository for an interactive prompt.

RDAP.domain("google.com")
# => {"objectClassName"=>"domain",
#  "handle"=>"2138514_DOMAIN_COM-VRSN",
#  "ldhName"=>"GOOGLE.COM",
#  "links"=>[...],
#  "status"=>[...],
#  "entities"=>[...],
#  "events"=>
#   [{"eventAction"=>"registration", "eventDate"=>"1997-09-15T04:00:00Z"},
#    {"eventAction"=>"expiration", "eventDate"=>"2028-09-14T04:00:00Z"},
#    {"eventAction"=>"last update of RDAP database", "eventDate"=>"2021-12-17T11:35:32Z"}],
#  "secureDNS"=>{"delegationSigned"=>false},
#  "nameservers"=>
#   [{"objectClassName"=>"nameserver", "ldhName"=>"NS1.GOOGLE.COM"},
#    {"objectClassName"=>"nameserver", "ldhName"=>"NS2.GOOGLE.COM"},
#    {"objectClassName"=>"nameserver", "ldhName"=>"NS3.GOOGLE.COM"},
#    {"objectClassName"=>"nameserver", "ldhName"=>"NS4.GOOGLE.COM"}],
#  "rdapConformance"=>
#   ["rdap_level_0", "icann_rdap_technical_implementation_guide_0", "icann_rdap_response_profile_0"],
#  "notices"=>[...]}
RDAP.ip("8.8.8.8") # IPv4
RDAP.ip("2620:119:35::35") # or IPv6
RDAP.as("16276") # AS Number ("autnum" in RDAP phraseology)

# there is also a lower level method accepting a type (:domain, :ip, :autnum) if needed
RDAP.query("16276", type: :autnum)

# Options
RDAP.domain("google.com", server: "https://rdap-bootstrap.arin.net/bootstrap") # Specify an alternative bootstrap server
RDAP.domain("google.com", server: "https://rdap.verisign.com/com/v1") # Or directly the target RDAP server if you know it
RDAP.domain("google.com", timeout: 20) # Customize open and read timeouts (default = 5 sec each)
RDAP.domain("google.com", headers: {'User-Agent' => 'My application name'}) # Override some HTTP request headers. Default headers are in RDAP::HEADERS

# Error handling
RDAP.domain("test.fr") # TLD not supported yet
# => RDAP::NotFound ([404] domain test.fr not found in IANA boostrap file)
RDAP.domain("jsiqpmcurt.design") # Domain not found
# => RDAP::NotFound ([404] Object not found)
RDAP.domain("jsiqpmcurt.com") # The message is not always exactly the same
# => RDAP::NotFound ([404] Not Found)
RDAP.domain("u$&~(!*@&@^#}") # Invalid URI
# => URI::InvalidURIError (bad URI(is not URI?): "https://rdap.org/domain/u$&~(!*@&@^#}")
RDAP.domain("broken") # Other type of unexpected server response
# => RDAP::ServerError ([500] Internal Server Error)

How does it work

The gem make a query to one of the publicly available RDAP bootstrap server (their responsibility is simply to check the bootstrap files and redirect you to the proper RDAP server), then it does the query to the target RDAP server and returns the JSON parsed. The gem currently use this public bootstrap server: https://rdap.org/ but it's possible to change for another one in case of problem or limitation. For example ARIN has it's own bootstrap server too: https://rdap-bootstrap.arin.net/bootstrap. It's also possible to host your own bootstrap server.

Changelog

0.1.5 (2022-12-29) - Add application/json, */* fallback Accept types to support rdap.nic.fr which does not like application/rdap+json (as of 2022-12-29). I also contacted them to report this issue.
0.1.4 (2022-02-01) - Wrap JSON parser errors as RDAP::InvalidReponse and also raise RDAP::EmptyResponse when body is missing
0.1.3 (2022-01-10) - Wrap SSL errors as RDAP::SSLError < ServerError < Error
0.1.2 (2022-01-07) - Added HTTP headers customization
0.1.1 (2021-12-19) - Added TooManyRequests expection in case of 429
0.1.0 (2021-12-17) - Initial version

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jarthod/rdap.

After checking out the repo, run bundle install to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Tests are using the vcr gem to record server responses so we don't hit them too quickly/often. This is nice and fast but if the server API even changes we may not notice it. So from time to time it can be intereting to re-record the responses: rm -R spec/fixtures && rake spec

Alternatives

If you're looking for a command line tool, you can check the excellent nicinfo (also written in Ruby). Also if you're just looking for one-off debugging and scripts, you can query a bootstrap endpoint directly using curl -L, example:

> curl -L https://rdap-bootstrap.arin.net/bootstrap/domain/google.com
{"objectClassName":"domain","handle":"2138514_DOMAIN_COM-VRSN","ldhName":"GOOGLE.COM","links":[{"value":"https:\/\/rdap.verisign.com\/com\/v1\/domain\/GOOGLE.COM","rel":"self","href":"https:\/\/rdap.verisign.com\/com\/v1\/domain\/GOOGLE.COM","type":"application\/rdap+json"},{"value":"https:\/\/rdap.markmonitor.com\/rdap\/domain\/GOOGLE.COM","rel":"related","href":"https:\/\/rdap.markmonitor.com\/rdap\/domain\/GOOGLE.COM","type":"application\/rdap+json"}],"status":["client delete prohibited","client transfer prohibited","client update prohibited","server delete prohibited","server transfer prohibited","server update prohibited"],"entities":[{"objectClassName":"entity","handle":"292","roles":["registrar"],"publicIds":[{"type":"IANA Registrar ID","identifier":"292"}],"vcardArray":["vcard",[["version",{},"text","4.0"],["fn",{},"text","MarkMonitor Inc."]]],"entities":[{"objectClassName":"entity","roles":["abuse"],"vcardArray":["vcard",[["version",{},"text","4.0"],["fn",{},"text",""],["tel",{"type":"voice"},"uri","tel:+1.2083895740"],["email",{},"text","[email protected]"]]]}]}],"events":[{"eventAction":"registration","eventDate":"1997-09-15T04:00:00Z"},{"eventAction":"expiration","eventDate":"2028-09-14T04:00:00Z"},{"eventAction":"last update of RDAP database","eventDate":"2021-12-17T11:35:32Z"}],"secureDNS":{"delegationSigned":false},"nameservers":[{"objectClassName":"nameserver","ldhName":"NS1.GOOGLE.COM"},{"objectClassName":"nameserver","ldhName":"NS2.GOOGLE.COM"},{"objectClassName":"nameserver","ldhName":"NS3.GOOGLE.COM"},{"objectClassName":"nameserver","ldhName":"NS4.GOOGLE.COM"}],"rdapConformance":["rdap_level_0","icann_rdap_technical_implementation_guide_0","icann_rdap_response_profile_0"],"notices":[{"title":"Terms of Use","description":["Service subject to Terms of Use."],"links":[{"href":"https:\/\/www.verisign.com\/domain-names\/registration-data-access-protocol\/terms-service\/index.xhtml","type":"text\/html"}]},{"title":"Status Codes","description":["For more information on domain status codes, please visit https:\/\/icann.org\/epp"],"links":[{"href":"https:\/\/icann.org\/epp","type":"text\/html"}]},{"title":"RDDS Inaccuracy Complaint Form","description":["URL of the ICANN RDDS Inaccuracy Complaint Form: https:\/\/icann.org\/wicf"],"links":[{"href":"https:\/\/icann.org\/wicf","type":"text\/html"}]}]}