/ 
WebService-IdoitAPI-v0.3.0
River stage zero No dependents
/ WebService::IdoitAPI

NAME

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

VERSION

Version v0.3.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)