view release on metacpan or  search on metacpan

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

=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.

This module is the first one written using L<Util::H2O::More>'s C<HTTPTiny2h2o>
method that looks for C<JSON> in the C<content> key returned via L<HTTP::Tiny>'s
response C<HASH>.

=head1 METHODS

=over 4

=item C<new>

Instantiates object reference. No parameters are accepted.

=item C<< apis( [id => INT] ) >>

Requires no parameters, but may be passed the named parameter C<id>.

When called without any parameters, caller will get an C<ARRAY> reference
list of all APIs currently being reported as working.

When passed a specific API id, the returned C<ARRAY> reference contains just
the requested API C<HASH>..

See the C<freeapis> client's C<apis> subcommand for an example of what can
be done with the output of this method.

=item C<< random >>

Accepts no parameters. Returns full C<HASH> of information on a random
API. See the C<freeapis> client's C<random> subcommand to see an example of
what can be done with the output.

=back

=head1 C<freeapis> OPTIONS

=over 4

=item C<apis [--id INT] [--details]>

If called without the option C<--id> parameter, this returns a full list
sorted by C<id> in ascending order. Optional parameter, C<--details>,
will dump all the information available for each API.

   shell> freeapi apis | sort -k2 -r -n | less # sorting on column #2
   319   80 Monster Hunter World API
   320   95 World Wonders
   321  100 Church Calendar API
   322   95 Motivational API
   323   95 Buddha Quotes API
   324   95 Fortnite API
   325   95 Dragon Ball API
   326   95 Demon Slayer API
   327   90 Jojo's Bizarre API
  Found 300 APIs

Naturally, it can be used with the commandline to sort on other fields such
as C<health>, e.g.:

  shell> freeapi apis | sort -k2 -r -n | less # sorting on column #2
  321  100 Church Calendar API
  191  100 IP Geolocation & Currency Converter
  129  100 IP Geolocation API