NAME

Webserver::KeyVal::API - Perl API client for the KeyVal service, https://keyval.org/.

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

SYNOPSIS

#!/usr/bin/env perl
    
use strict;
use warnings;

my $key = shift @ARGV;

use Webservice::KeyVal::API qw//;
my $client     = Webservice::KeyVal::API->new;
my $val        = "foo";
my $resp       = $client->set($key => $val);    # can die
printf "%s %s\n", $resp->key, $resp->val;

# ... later get the value back,
$resp = $client->get($key);                     # can die
printf "%s %s\n", $resp->key, $resp->val;

kv Commandline Client

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

shell> kv -k mykey -v "this is a value..."  # note: key and value are limited to 101 charactersR
mykey this is a value...                    # key and value are echo'd out to STDIN

# -k is optional, the webservice provides a unique GUID

shell> kv set -v "this is a value..."
f7b1d193-16db-4ef6-a447-32ee0734c46f this is a value...

# value can be piped in via "-v -"

shell> echo "this is a value..." | kv set -v -
16aa9ec9-faa1-479e-a575-386809ff883b this is a value...

# you can do fun shell tricks like this, to get the key you just set

shell> kv get -k $(kv set -v foobar | awk '{print $1}')
21348201-cf45-4dfb-a92e-e6ccf04ba395 foobar

DESCRIPTION

This is the Perl API for the KeyVal, profiled at https://www.freepublicapis.com/keyval-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.

set KEY = VAL>

This call will set the KEY to the value of VAL at the KeyVal webservice for later retreival.

KEY may also be undef, and in fact this is recommended since the service doesn't seem to delete keys and there is no way to update them.

It is perfectly valid to do the following:

use Webservice::KeyVal qw//;
my $client     = Webservice::KeyVal::API->new; 
my $val        = "foo";
my $resp       = $client->set(undef => $val);

The webservice will return a guaranteed unique GUID as a key, and you may use this after to get the value back. If there is an upstream key conflict, then the webservice returns an -KEY-ALREADY-EXISTS- error. This methods will die if that happens.

It is not documentated, but has been determined empirically that the maximum length for both keys and values is 101 characters. If a key or value is sent that is longer than this length, the webservice will return a -KEY-OR-VALUE-TOO-LONG- error.

Also note, the webservice always returns an HTTP status of 200 OK, the status field of the returned JSON must be checked to determine if the was a failure. This module checks for anything other than status = "SUCCESS"> and will die if this condition is detected.

get

kv OPTIONS

set -v 'value ...' [-k KEY]

-v is required, but can take a special value of a single dash, -; this will tell the client to read in the value via <STDIN>. See the example in the SYNOPSIS.

shell>kv -k mykey -v "some value"
mykey some value

-k is optional, and it is actually recommend that this not be sent so that the webservice can accept the value and return back a unique GUID that you use to later retreived the value.

shell> echo "this is a value..." | kv set -v -
16aa9ec9-faa1-479e-a575-386809ff883b this is a value...

Keys and values are restricted to a length of 101 characters. Values can also not be deleted or updated, per the KeyVal API specification.

get -k KEY]

-k is required and specifies a valid key. The webservice will return the value of this key, and this client will print it out for you to use.

Internal Methods

There are no internal methods to speak of.

NOTES ABOUT THE API

Through the development of this module and associated commandline utility, kv, it has been noted that:

HTTP Status

the API always returns 200 OK to check if the call succeeded or failed, one must check the status field.

Length limits

keys and values are limited to 101 characters each

Don't specify key names

it is almost always to just send the value and not specify a key, the chances of collision with existing keys is high; better to let the webservice give you the GUID it can return; this will always be ok unless the value sent is greater than 101 characters

ENVIRONMENT

Nothing special required.

AUTHOR

Brett Estrade <oodler@cpan.org>

BUGS

Please report.

LICENSE AND COPYRIGHT

Same as Perl/perl.