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 $url = 'https://www.myjsons.com';
   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

https://www.myjsons.com is a handy service that can host some JSON data 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 https://github.com/polettix/WebService-MyJSONs.

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

    http://www.apache.org/licenses/LICENSE-2.0

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.

cpanm WebService::MyJSONs

perl -MCPAN -e shell
install WebService::MyJSONs