view release on metacpan or  search on metacpan

lib/Acme/Free/Public/APIs.pm  view on Meta::CPAN

package Acme::Free::Public::APIs;

use strict;
use warnings;

our $VERSION = '0.9.10';

use HTTP::Tiny;
use JSON            qw/decode_json/;
use Util::H2O::More qw/baptise d2o HTTPTiny2h2o/;

use constant {
    BASEURL => "https://www.freepublicapis.com/api/",
};

sub new {
    my $pkg  = shift;
    my $self = baptise { ua => HTTP::Tiny->new }, $pkg;
    return $self;
}

# https://www.freepublicapis.com/api/apis
# https://www.freepublicapis.com/api/apis/275

sub apis {
    my $self   = shift;
    my $params = d2o -autoundef, { @_ };
    my $URL    = sprintf "%s/apis", BASEURL;

    my $ret = [];
    if ($params->id) {
      $URL = sprintf "%s/%d", $URL, $params->id;
      my $resp = HTTPTiny2h2o $self->ua->get($URL);
      $ret = d2o -autoundef, [ $resp->content ]; # preset single item in an ARRAY
    }
    else {
      my $resp = HTTPTiny2h2o $self->ua->get($URL);
      $ret = $resp->content;
    }

    return $ret;
}


# https://www.freepublicapis.com/api/random

sub random {
    my $self = shift;
    my $URL  = sprintf "%s/random", BASEURL;
    my $resp = HTTPTiny2h2o $self->ua->get($URL);
    return $resp->content;
}

1;

__END__
=encoding UTF-8

=head1 NAME

Acme::Free::Public::APIs - Perl API client for FreePublicAPI.com's API for
for listing APIs.

This module provides the client, "freeapis", that is available via C<PATH>
after install.

=head1 SYNOPSIS

  #!/usr/bin/env perl

  use strict;
  use warnings;

  use Acme::Free::Public::APIs qw//;

  my $api     = Acme::Free::Public::APIs->new->random;
  my $out     = <<EOAPI;
  id:            %d
  title:         %s%s
  site URL:      %s
  methods:       %s
  health:        %d
  documentation: %s
  description:   %s
  EOAPI
  printf $out, $api->id, ($api->emoji) ? sprintf("(%s) ",$api->emoji) : "",, $api->title, $api->source, $api->methods, $api->health, $api->documentation, $api->source;

=head2 C<freeapis> Commandline Client

After installing this module, simply run the command C<freeapis> without
any arguments, and it will print information regarding a randomly selected
free API that is listed on its site. Below you may see a project familiar
to some in the Perl community, the L<https://world.openfoodfacts.org/> Project.

  shell> freeapis
  id:            174
  title:         (🍲) OpenFoodFacts
  site URL:      https://freepublicapis.com/openfoodfacts
  methods:       1
  health:        84
  documentation: https://world.openfoodfacts.org/data
  description:   Open Food Facts is a food products database made by everyone, for everyone. You can use it to make better food choices, and as it is open data, anyone can re-use it for any purpose.
  shell>

=head1 DESCRIPTION

This is the Perl API for the Dog API, profiled at L<https://www.freepublicapis.com/api>.

Contributed as part of the B<FreePublicPerlAPIs> Project described at,
L<https://github.com/oodler577/FreePublicPerlAPIs>.

This fun module is to demonstrate how to use L<Util::H2O::More> and
L<Dispatch::Fu> to make creating easily make API SaaS modules and
clients in a clean and idiomatic way. These kind of APIs tracked at
L<https://www.freepublicapis.com/> are really nice for fun and practice
because they don't require dealing with API keys in the vast majority of cases.