/ 
InternetData-1.8.2
/ 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 string, and no Authorization header is sent. Every database endpoint published today answers 401 without one.

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.