NAME

Acme::Free::Dog::API - Perl API client for the Dog API service, https://dog.ceo/dog-api.

This module provides the client, "fletch", that is available via PATH after install.

SYNOPSIS

  #!/usr/bin/env perl
    
  use strict;
  use warnings;
  
  use Acme::Free::Dog::API qw//;
  
  my $fletch = Acme::Free::Dog::API->new;

  printf "%s\n", $fletch->random;

fletch Commandline Client

After installing this module, simply run the command fletch without any argum ents to get a URL for a random dog image. See below for all subcommands.

  shell> fletch
  https://images.dog.ceo/breeds/basenji/n02110806_2249.jpg
  shell>

DESCRIPTION

This is the Perl API for the Dog API, profiled at https://www.freepublicapis.com/dog-api.

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

This fun module is to demonstrate how to use Util::H2O::More and Dispatch::Fu to make creating easily make API SaaS modules and clients in a clean and idiomatic way. These kind of APIs tracked at 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 Util::H2O::More's HTTPTiny2h2o method that looks for JSON in the content key returned via HTTP::Tiny's response HASH.

METHODS

new

Instantiates object reference. No parameters are accepted.

breeds

Makes the SaaS API call to get the list of all breeds. It accepts no arguments.

This list determines what is valid when specifying the breed in using random.

images(breed => STRING)

Fetches a long list of images URLs for the specified breed. There seemed to be now way to get an imagine for a subbreed, so for breeds that do have subbreeds, the list of image URLs contains some random assortment of all subbreeds.

random([breed => STRING])

Returns a random dog image URL. You may specify the breed with the named parameter, breed.

subreeds(breed => STRING)

Given the named parameter, breeds, returns a list of subbreeds if they exist.

fletch OPTIONS

breeds

Prints out a list of supported breeds. Useful for determining what is accepted upstream when using the random with the --breed flag used.

If the a breed has 1 or more subbreeds, it is indicated with a + sign.

This command can be used in combination with the subbreeds subcommand, e.g.,

  fletch breeds | awk '{ if ($2 == "+") print $1 }' | xargs -I% fletch subbreeds --breed %

In fact, any subcommand that takes that --breed argument can be combined with this subcommand in a way that makes for some very powerful commandline dog-fu!

images --breed BREED

The --breed argument is required.

Provides a list of all URLs for the specified BREED. The API call behind this subcommand doesn't support listing image URLs by subbreed, so for breeds that are further categorized by subbreed the results contain a mix of them.

This comand can be used incombination with the breeds subcommand to get a bunch of images for each breed (no support in the API for subbreed image fetching).

  fletch breeds | awk '{print $1}' | xargs -I% fletch images --breed %

random [--breed BREED]

Prints the random dog image URL to STDOUT. You may optionally specify a breed.

This command can be used in combination with the breeds command to get a random image URL for all breeds.

  fletch breeds | awk '{print $1}' | xargs -I% fletch random --breed %

subbreeds --breed BREED

The --breed argument is required.

Given a breed, lists out the subbreeds. It handles breeds that have no subbreeds, but this command can be used in combination with the breeds command to fetch all subbreeds for only breeds that have 1 or more subbreeds. See the section on the breeds subcommand for more..

Internal Methods

There are no internal methods to speak of.

ENVIRONMENT

Nothing special required.

AUTHOR

Brett Estrade <oodler@cpan.org>

BUGS

Please report.

LICENSE AND COPYRIGHT

Same as Perl/perl.