view release on metacpan or  search on metacpan

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

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
   92   99 French Address API
   94   95 Carbon Intensity API
   90   95 JSONPlaceholder
   88   95 Stadt Land Fluss
   80   95 Dungeons and Dragons
   77   95 Digimon API
   75   95 Rick and Morty API
   72   95 kanye.rest
   71   95 Coinpaprika API
   70   95 Met Museum Collection
   68   95 Data USA
   62   95 Harry Potter API
   54   95 Star Wars API
   53   95 Nationalize API
   51   95 The Cat API
   48   95 Open Brewery DB
   47   95 Fruityvice
   46   95 Useless Facts API
   45   95 Corporate Bullshit Generator
   44   95 Virenmonitoring API
   36   95 Open Meteo
   35   95 CoinGecko API
   34   95 Agify.io
  326   95 Demon Slayer API
  ...
  shell>

Similarly, some clever commandline antics will allow one to do specific
queries by C<id> (first column) when piped to other commands.

When C<--id> is specified, it outputs just the corresponding line for the
referened API.

  shell>freeapi apis --id 321
  321  100 Church Calendar API

When C<--details> is added, it shows the full amount of information:

  shell>freeapi apis --id 321 --details
  id:            321
  title:         (📅) Church Calendar API
  site URL:      https://freepublicapis.com/church-calendar-api
  methods:       2
  health:        100
  documentation: http://calapi.inadiutorium.cz/api-doc
  description:   The Church Calendar API provides access to calendar data for any day, allowing users to retrieve various liturgical celebrations and details. It supports multiple languages and enables specific queries for feast names and calendar de...
  Found 1 API

=item C<random>

This subcommand takes no arguments. When run it prints out to C<STDOUT> all
the information provided for it.

  shell>
  id:            320
  title:         (🌍) World Wonders
  site URL:      https://freepublicapis.com/world-wonders
  methods:       2
  health:        95
  documentation: https://www.world-wonders-api.org/v0/docs