update documentation to cover searches

parent f6ca9565
......@@ -9,6 +9,10 @@
my $rdap = Net::RDAP->new;
#
# traditional lookup:
#
# get domain info:
$object = $rdap->domain(Net::DNS::Domain->new('example.com'));
......@@ -17,7 +21,22 @@
$object = $rdap->ip(Net::IP->new('2001:DB8::/32'));
# get info about AS numbers:
$object = $rdap->ip(Net::ASN->new(65536));
$object = $rdap->autnum(Net::ASN->new(65536));
#
# search functions:
#
my $server = Net::RDAP::Service->new("https://www.example.com/rdap");
# search for domains by name:
my $result = $server->domains('name' => 'ex*mple.com');
# search for entities by name:
my $result = $server->entities('fn' => 'J*n Doe');
# search for nameservers by IP address:
my $result = $server->nameservers('ip' => '192.168.56.101');
# DESCRIPTION
......@@ -45,9 +64,8 @@ interface to information about all unique Internet identifiers.
$rdap = Net::RDAP->new(%OPTIONS);
Constructor method, returns a new object.
Supported options:
Constructor method, returns a new object. %OPTIONS is optional, but
may contain any of the following options:
- `use_cache` - if true, copies of RDAP responses are stored on
disk, and are updated if the copy on the server is more up-to-date.
......@@ -68,6 +86,19 @@ domain (such as `168.192.in-addr.arpa`).
If there was an error, this method will return a [Net::RDAP::Error](https://metacpan.org/pod/Net::RDAP::Error).
### Note on Internationalised Domain Names (IDNs)
Domain names which contain characters other than those from the ASCII-compatible
range must be encoded into "A-label" (or "Punycode") format before being passed
to `Net::DNS::Domain`. You can use `Net::LibIDN` or `Net::LibIDN2` to
perform this encoding:
use Net::LibIDN;
my $name = "espécime.com";
my $domain = $rdap->domain->(Net::DNS::Domain->new(idn_to_ascii($name, 'UTF-8')));
## IP Lookup
$object = $rdap->ip($ip);
......@@ -107,11 +138,11 @@ per RFC 8521.
## Directly Fetching Known Resources
$object = $rdap->fetch($url);
$object = $rdap->fetch($url, %OPTIONS);
$object = $rdap->fetch($link);
$object = $rdap->fetch($link, %OPTIONS);
$object = $rdap->fetch($object);
$object = $rdap->fetch($object, %OPTIONS);
The first and second forms of the `fetch()` method retrieve the
resource identified by `$url` or `$link` (which must be either a
......@@ -144,6 +175,17 @@ In order for this form to work, the object must have a `self` link:
[Net::RDAP](https://metacpan.org/pod/Net::RDAP) will auto-create one for objects that don't have one if it
can.
`%OPTIONS` is an optional hash containing additional options for the query. At
the moment, only the `user` and `pass` options are supported; if provided,
they will be sent to the server in an HTTP Basic Authorization header field.
## Performing Searches
RDAP supports a limited search capability, but you need to know in
advance which RDAP server you want to send the search query to. The
`Net::RDAP::Service` class allows you to prepare and submit search
queries to specific RDAP servers.
## RDAP User Agent
# access the user agent
......@@ -251,3 +293,11 @@ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# POD ERRORS
Hey! **The above document had some coding errors, which are explained below:**
- Around line 137:
Non-ASCII character seen before =encoding in '"espécime.com";'. Assuming UTF-8
......@@ -29,6 +29,10 @@ L<Net::RDAP> - an interface to the Registration Data Access Protocol
my $rdap = Net::RDAP->new;
#
# traditional lookup:
#
# get domain info:
$object = $rdap->domain(Net::DNS::Domain->new('example.com'));
......@@ -39,6 +43,21 @@ L<Net::RDAP> - an interface to the Registration Data Access Protocol
# get info about AS numbers:
$object = $rdap->autnum(Net::ASN->new(65536));
#
# search functions:
#
my $server = Net::RDAP::Service->new("https://www.example.com/rdap");
# search for domains by name:
my $result = $server->domains('name' => 'ex*mple.com');
# search for entities by name:
my $result = $server->entities('fn' => 'J*n Doe');
# search for nameservers by IP address:
my $result = $server->nameservers('ip' => '192.168.56.101');
=head1 DESCRIPTION
L<Net::RDAP> provides an interface to the Registration Data Access
......@@ -504,6 +523,13 @@ sub request {
=pod
=head2 Performing Searches
RDAP supports a limited search capability, but you need to know in
advance which RDAP server you want to send the search query to. The
C<Net::RDAP::Service> class allows you to prepare and submit search
queries to specific RDAP servers.
=head2 RDAP User Agent
# access the user agent
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment