NAME
WebService::MyJSONs - Perl SDK to consume the MyJSONs web service
VERSION
This document describes WebService::MyJSONs version 0.002.
SYNOPSIS
Functional interface:
use WebService::MyJSONs qw< myjsons_put myjsons_get >;
# create a new item, get item's code back
my $code = myjsons_put({ foo => 'bar' });
# retrieve data for $code
my $retrieved_data = myjsons_get($code);
# update data for $code
myjsons_put($code, { foo => 'bar', baz => 42 });
Function myjsons_put doubles down on creation of a new slot or update
of the slot, depending on the number of parameters (one or two,
respectively). The interface above takes care to convert it to/from
JSON as needed.
JSON-specific API:
use WebService::MyJSONs qw< myjsons_put_json myjsons_get_json >;
my $code = myjsons_put_json('{"foo":"bar"}');
my $json = myjsons_get_json($code);
myjsons_put_json($code, '{"foo":"bar", "baz": "yay!"}');
Again, myjsons_put_json doubles down on creation and update.
Object-oriented interface (remote JSON item code is cached when
available):
use WebService::MyJSONs;
my $mj1 = WebService::MyJSONs->new;
# initialize with a $code
$code = '5ef6366';
my $mj2 = WebService::MyJSONs->new(code => $code);
# set endpoint explicitly (e.g. a different one)
my $mj3 = WebService::MyJSONs->new(endpoint => $url);
Objects that do not have a cached code inside will invoke the creation
of a new remote item and then cache the code returned by the web
service.
In the next example, $mj starts without a code inside, so the first put
takes care to create a new remote item and cache its code inside the
object, while the second put is an update to that remote item.
my $mj = WebService::MyJSONs->new;
$mj->put({ foo => 'bar', hex => [ 0 .. 9, 'a' .. 'f' ] });
say $mj->code;
my $retrieved_data = $mj->get;
$mj->put({ foo => 'bar', hex => [ 0 .. 9, 'A' .. 'F' ] });
There’s of course the counterpart when playing directly with JSON
strings:
my $mj = WebService::MyJSONs->new;
$mj->put_json('{"foo":"bar"}');
my $json = $mj->get_json;
$mj->put_json('{"foo":"barbaz"}');
Using a different remote JSON item code (does not update the cached
one):
my $mj = WebService::MyJSONs->new($somecode);
my $data = $mj->get($code);
my $json = $mj->get($json);
$mj->put($code, $data);
$mj->put_json($code, $json);
put/put_json can also act as constructors when called as class methods:
my $mj_a = WebService::MyJSONs->put($data);
my $mj_b = WebService::MyJSONs->put($code, $data);
my $mj_c = WebService::MyJSONs->put_json($json);
my $mj_d = WebService::MyJSONs->put_json($code, $json);
get/get_json can be called as class methods as well:
my $data = WebService::MyJSONs->get($code);
my $json = WebService::MyJSONs->get_json($code);
DESCRIPTION
for us, e.g. for test/mock purposes.
As long as it keeps its interface as of the end of October 2022, this
module can help interacting with the web service.
See the "SYNOPSIS" for an overview of the different ways of using it.
INTERFACE
There are a functional and an object-oriented interfaces provided by
the module. It can also act as a modulino.
Modulino
The module can be invoked as a Perl program, like this:
# print a help message
perl /path/to/MyJSONs.pm
# create a new remote item, new code is printed on STDOUT
code=$(perl /path/to/MyJSONs.pm put </path/to/stuff.json)
# update a remote item
perl /path/to/MyJSONs.pm put $somecode </path/to/stuff.json
# retrieve JSON stuff, printed on STDOUT
perl /path/to/MyJSONs.pm get $somecode | jq .
The actual implementation is provided by "myjsons_cmdline".
As there is no dependency that is not in CORE, it's possible to copy
the Perl module file somewhere in PATH (e.g. with file name myjsons)
and invoke it as a program.
Functional Interface
All of the functions below can be imported at once using import string
:all, like this:
use WebService::MyJSONs ':all';
myjsons_cmdline
myjsons_cmdline(); # 1
myjsons_cmdline('help'); # 2
myjsons_cmdline('get', $code); # 3
myjsons_cmdline('put'); # 4
myjsons_cmdline('put', $code); # 5
Implement a simple program to use the functionalities from the command
line, like this:
use WebService::MyJSONs 'myjsons_cmdline';
myjsons_cmdline(@ARGV);
All JSON input/output is performed through STDIN/STDOUT respectively.
Calls 1 and 2 print a help message and exit with status code 1.
Call 3 retrieves the JSON string at $code and prints it on STDOUT.
Calls 4 and 5 read the JSON string from STDIN and send it to the remote
server. 4 creates a new item, 5 updates the object at $code. Both print
out the item's code.
myjsons_get
my $data = myjsons_get($code);
Get data from the web service, pointed by $code. The JSON object
retrieved is turned into a Perl data structure by means of JSON::PP.
myjsons_get_json
my $data = myjsons_get_json($code);
Get a JSON string from the web service, pointed by $code.
myjsons_put
my $code = myjsons_put($data);
myjsons_put($code, $data);
Put some data in the web service. $data is turned into a JSON string by
means of JSON::PP.
The first call only provides $data and triggers the addition of a new
item in the web service, returning the code of the newly created item.
The second call example provides both $code and $data, leading to an
update operation (unless $code is undef). It also returns the code.
myjsons_put_json
my $code = myjsons_put_json($json);
myjsons_put_json($code, $json);
Put a JSON string in the web service.
The first call only provides $json and triggers the addition of a new
item in the web service, returning the code of the newly created item.
The second call example provides both $code and $json, leading to an
update operation (unless $code is undef). It also returns the code.
Object-oriented Interface
The object-oriented interface provides a finer granularity control.
code
my $code = $mj->code;
$mj->code($new_code);
Accessor for the code, i.e. the unique identifier of the JSON string in
the web service.
get
my $data = $mj->get; # instance method, cached code
$data = $mj->get($code); # instance method, explicit code
$data = WebService::MyJSONs->get($code); # class method
Retrieve data, taking care to transform the retrieved JSON string into
a Perl data structure with JSON::PP.
The instance call with the $code uses the provided value, leaving the
cached code (if any) unchanged.
get_json
my $json = $mj->get_json; # instance method, cached code
$json = $mj->get_json($code); # instance method, explicit code
$json = WebService::MyJSONs->get_json($code); # class method
Retrieve a JSON string.
The instance call with the $code uses the provided value, leaving the
cached code (if any) unchanged.
new
my $mj = WebService::MyJSONs->new(%args);
Constructor. Allowed keys are:
code
a unique code for a remote JSON item. See also "code".
endpoint
the endpoint to use instead of the default one. See also "Package
Variables".
response_callback
A callback function with the following signature:
sub ($response) { ... }
After each call to HTTP::Tiny, a $response object is retrieved and
then passed to this callback function. It can be e.g. useful for
troubleshooting purposes.
put
$mj->put($data); # 1
$mj->put($code, $data); # 2
my $obj = WebService::MyJSONs->put($data); # 3
my $obj = WebService::MyJSONs->put($code, $data); # 4
Transform $data into a JSON string with JSON::PP and store it remotely.
Alternative 1 generates a new item in the web service, unless a "code"
is cached (either because of a previous invocation, or because passed
explicitly upon construction). If the code is available, it acts as an
updater.
Alternative 2 updates the remote item corresponding to $code if this is
defined. If $code is undef, it acts just like 1.
Alternative 3 acts as a constructor that also creates a remote item and
sets the object's "code" accordingly.
Alternative 4 with a defined $code acts as a constructor with the $code
and then updates the corresponding remote object. If $code is undef, it
acts just like 3.
put_json
$mj->put_json($json); # 1
$mj->put_json($code, $json); # 2
my $obj = WebService::MyJSONs->put_json($json); # 3
my $obj = WebService::MyJSONs->put_json($code, $json); # 4
See "put", the only difference is that JSON strings are used instead of
data structures, so no automatic encoding happens.
Package Variables
The package variable $DEFAULT_ENDPOINT can be manipulated to point the
module to a different web service instance, providing the same API. Its
value is used by the functions in the "Functional Interface", as well
as the default endpoint value in the "Object-oriented Interface".
BUGS AND LIMITATIONS
Minimum perl version 5.24.
Report bugs through GitHub (patches welcome) at
AUTHOR
Flavio Poletti <flavio@polettix.it>
COPYRIGHT AND LICENSE
Copyright 2022 by Flavio Poletti <flavio@polettix.it>
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.