The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-IdoitAPI-0.4.0
River stage zero No dependents
++
/ WebService::IdoitAPI

NAME

WebService::IdoitAPI - a library to access the i-doit JSON RPC API

VERSION

version 0.4.0

SYNOPSIS

Allow access to the JSON-RPC-API of i-doit using Perl data structures.

    use WebService::IdoitAPI;

    my $config = {
        apikey => 'your_key_here',
        password => 'your_password_here',
        url => 'full_url_to_json_rpc_api',
        username => 'your_username_here',
    };

    my $idoitapi = WebService::IdoitAPI->new( $config );

    my $request = {
        method => $idoit_method,
        params => {
            # your params here
        }
    };
    my $reply = $idoitapi->request($request);

SUBROUTINES/METHODS

new

    my $config = {
        apikey => 'your_key_here',
        password => 'your_password_here',
        username => 'your_username_here',
        url => 'full_url_to_json_rpc_api',
    };

    my $idoitapi = WebService::IdoitAPI->new( $config );

Create a new WebService::IdoitAPI object and provide it with the credentials and location to access the JSON-RPC-API.

Depending on the configuration of your i-doit instance, you may need a username and password and an API key, or the key may suffice.

This function throws an exception when either $config->{apikey} or $config->{url} is missing.

request

    my $req = {
        method => $idoit_method,
        params => {
            # your params here
        }
    };
    my $res = $idoitapi->request($req);

    if ($res) {
        if ($res->is_error) {
            print "Error : ", $res->error_message;
        }
        else {
            # you can find the reply in $res->result
        }
    }
    else {
        print $idoitapi->{client}->status_line;
    }

Sends the given request as JSON-RPC-API call to the configured i-doit instance.

$request-{method}> can be any method supported by the i-doit JSON-RPC-API. $request-{params}> must match that method.

In case of error, the method returns undef. Otherwise it returns a JSON::RPC::Legacy::ReturnObject.

The method automatically adds the JSON parameters version, id and params.language if they are not provided in $request. It takes care to add the credentials, that were given in the configuration hash to method new().

login

    my $res = $idoitapi->login($username, $password);

or

    my $res = $idoitapi->login();

Sends an idoit.login API call to create a session. If the call is successful, the returned session ID is used henceforth instead of username and password;

If you don't provide $username and $password, the method takes the values given in the configuration hash to the method new().

logout

    my $res = $idoitapi->logout();

Sends an idoit.logout API call to close a session. A previous used session ID is deleted.

If the $idoitapi object is logged in when it is destroyed - for instance because it goes out of scope - this method is automatically called to close the session on the server.

is_logged_in

    if (not $idoitapi->is_logged_in()) {
        $idoitapi->login($username,$password);
    }

Tests if the WebService::IdoitAPI object has a session ID - that means it is logged in.

read_config

    my $config = WebService::IdoitAPI::read_config($path);
    my $api = WebService::IdoitAPI->new( $config );

This is a convenience function, that tries to extract the necessary keys (apikey password url username) from the file whose name is given by $path.

If $path is not given or undef, the function tries some known paths of configuration files. Currently there is only known path:

$ENV{HOME}/.idoitcli/config.json

the configuration file used by the PHP CLI client idoitcli.

AUTHOR

Mathias Weidner, <mamawe at cpan.org>

BUGS

Please report any bugs or feature requests to bug-webservice-idoitapi at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-IdoitAPI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WebService::IdoitAPI

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by Mathias Weidner.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)