/ 
InternetData-1.9.4
/ InternetData

NAME

InternetData - the official Perl client for the InternetData API

SYNOPSIS

use InternetData;

my $client = InternetData->new(api_key => $ENV{INTERNETDATA_API_KEY});

for my $db (@{ $client->database->list }) {
    next unless $db->{standing} eq 'licensed';
    my $id = $db->{versions}[-1]{id};
    $client->database->download($id, 'csvgz', "./$id.csv.gz");
}

DESCRIPTION

Downloads InternetData's licensed IP and network databases, and reads what the API publishes about them: the catalog, per-database metadata, checksums, and your organization's recent download attempts.

Every database endpoint published today needs a key carrying the db.download scope. "new" takes one as an option rather than requiring it: a client built without a key sends no Authorization header at all, which is what a database served without a license would need, and what "oauth" needs anyway.

METHODS

The seven database calls live on InternetData::Database, reached as "database". Each has a _p twin returning a Mojo::Promise and takes a per-call retries option, and all but the two transfers a per-call timeout. Failures die with an InternetData::Error. The OAuth sign-in lives on InternetData::Oauth, reached as "oauth".

new

my $client = InternetData->new(api_key => '...', %options);
api_key

A console-issued key carrying the db.download scope. Keys are default-deny, so an existing key does not reach these endpoints until the scope is added to it. Optional: omit it, or pass an empty or blank one, and no Authorization header is sent. Every database endpoint published today answers 401 without one. The key is trimmed, so one read from a file with its newline works; a key still holding a control character croaks here.

base_url

Defaults to https://internetdata.io.

retries

Attempts after a retryable failure. Defaults to 2, and is overridable per call. Each retry waits the server's Retry-After when it sent one, otherwise a backoff of 250 ms that doubles per retry, up to 16 seconds. A Retry-After longer than about 24.8 days is waited out on that backoff instead.

timeout

Per-request timeout in seconds. Defaults to 30, and is overridable per call. It bounds each attempt, so a retried call can take longer in total, and it is lifted for a file transfer, which is not a request whose duration a caller can predict.

ua

Your own Mojo::UserAgent, for a proxy or custom TLS settings. The client sets max_redirects to 0 on whichever agent it is given: the download endpoint answers 302 and that redirect is the answer, so following it would pull a multi-gigabyte file into memory.

database

my $databases = $client->database->list;

The licensed database downloads. See InternetData::Database.

oauth

my $device = $client->oauth->device_authorization('your-client-id');

Signs a person in on their own machine with the OAuth device flow, so a program can be handed one of their API keys instead of asking for it. See InternetData::Oauth.

NON-BLOCKING USE

Every call has a _p twin returning a Mojo::Promise, on InternetData::Database and InternetData::Oauth alike, so the library drops into a Mojolicious application without a worker. The blocking forms are those promises plus a wait, so nothing is duplicated and both paths retry identically.

$client->database->list_p
    ->then(sub { say $_->{base} for @{ shift() } })
    ->catch(sub { warn shift })
    ->wait;

Inside an already running Mojo::IOLoop the blocking forms cannot work and croak saying so. Use the _p forms there.

SEE ALSO

InternetData::Database, InternetData::Error, InternetData::Oauth.

LICENSE

MIT. Copyright Mslm Dev.