GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  WEBSERVICE::REDMINE (3)

.ds Aq ’

NAME

WebService::Redmine - Wrapper for RedMine REST API (http://www.redmine.org/projects/redmine/wiki/Rest_api).

CONTENTS

SYNOPSIS



        use WebService::Redmine;
        my $redminer = WebService::Redmine->new(
                host => example.com/redmine,
                key  => xxx,
        );
        # password-based auth is also supported:
        #my $redminer = WebService::Redmine->new(
        #       host => example.com/redmine,
        #       user => redminer,
        #       pass => p@s$w0rD,
        #);

        my $project = $redminer->createProject({ project => {
                identifier  => my-project,
                name        => My Project,
                description => My project, created with *WebService::Redmine*,
        }});
        if (!$project) {
                say STDERR Error(s) creating project: , join("\n", map { $_ } @{ $redminer->errorDetails->{errors} });
                exit 1;
        }
        my $project_id = $project->{project}{id};

        $redminer->updateProject($project_id, { project => {
                parent_id       => 42, # Make a project with numeric ID 42  parent for $project_id
                inherit_members => 1,  # Inherit all members and their permissions from the parent
        }});
       
        my $issue = $redminer->createIssue({ issue => {
                project_id  => $project_id,
                subject     => Test issue for WebService::Redmine,
                description => Issue description,
        }});

        $redminer->deleteProject($project_id);



DESCRIPTION

This module is a client for RedMine REST API. Please note that although RedMine API is designed to support both JSON and XML, this module is <B>JSON onlyB>.

METHODS NAMING AND OTHER CALL CONVENTIONS

All methods are dynamically converted to actual HTTP requests using following conventions.

    Getting a Collection of Objects



        $redminer->projects;     # ->users,     ->issues,     ->timeEntries     ...
        $redminer->getProjects;  # ->getUsers,  ->getIssues,  ->getTimeEntries  ...
        $redminer->readProjects; # ->readUsers, ->readIssues, ->readTimeEntries ...
       
        # Second page when displaying 10 items per page:
        $redminer->projects({ offset => 9, limit => 10 });

        # Filtering issues:
        $redminer->issues({ project_id => 42, assigned_to_id => me });



    Getting an Object



        $redminer->project(1);     # ->user(1),      ->issue(1),     ->timeEntry(1)     ...
        $redminer->getProject(1);  # ->getUser(1),   ->getIssue(1),  ->getTimeEntry(1)  ...
        $redminer->readProject(1); # ->readUsers(1), ->readIssue(1), ->readTimeEntry(1) ...
       
        # Showing an object with additional metadata:
        $redminer->issue(1, { include => relations,changesets });



    Creating an Object



        $redminer->createProject({
                # ...
        }); # ->createUser, ->createIssue, ->createTimeEntry ...



    Updating an Object



        $redminer->updateProject(1, {
                # ...
        }); # ->updateUser(...), ->updateIssue(...), ->updateTimeEntry(...) ...



    Deleting an Object



        $redminer->deleteProject(1); # ->deleteUser(1), ->deleteIssue(1), ->deleteTimeEntry(1) ...



    Objects Belonging to Other Objects



        #
        # Example for project membership(s)
        #
        my $project_id    = 42;
        my $membership_id = 42;

        # Listing *project* memberships and creating a membership within a *project*
        # require identifying a project and thus have to be spelled like this:
        $redminer->projectMemberships($project_id, { limit => 50 });
        $redminer->createProjectMembership($project_id, { ... });

        # Viewing/Updating/Deleting a membership is performed directly by its ID, thus:
        my $membership = $redminer->membership($membership_id);
        $redminer->updateMembership($membership_id, { ... });
        $redminer->deleteMembership($membership_id);



    Complex Object Names

Such complex names as TimeEntry which should be dispatched to time_entries are recognized and thus can be spelled in CamelCase (see examples above). If this is not the case, please report bugs.

    Return Values

All successfull calls return hash references. For update* and delete* calls hash references are empty.

If a call fails, undef is returned. In this case detailed error information can be retrieved using errorDetails method:



        if (!$redminer->deleteIssue(42)) {
                my $details = $redminer->errorDetails;
                # Process $details here...
        }



METHODS

    new



        my $redminer = WebService::Redmine->new(%options);



Following options are recognized:
o <B>hostB>: RedMine host. Beside host name, may include port, path and/or URL scheme (http is used by default).
o key: API key. For details, please refer to http://www.redmine.org/projects/redmine/wiki/Rest_api#Authentication
o <B>userB>, <B>passB>: User name and password for password-based authentication
o work_as: User login for impersonation. For details, please refer to http://www.redmine.org/projects/redmine/wiki/Rest_api#User-Impersonation.
o <B>no_wrapper_objectB>: Automatically add/remove wrapper object for data. See below.
no_wrapper_object

By default RedMine API requires you to wrap you object data:



        my $project = $redminer->createProject({
                project => {
                        identifier => some-id,
                        name       => Some Name,
                }
        });
        # $project contains something like
        # { project => { id => 42, identifier => some-id, name => Some Name ... } }



By default this module follows this convention. However, if you turn on the no_wrapper_object flag



        my $redminer = WebService::Redmine->new(
                host => example.com/redmine,
                key => xxx,
                no_wrapper_object => 1,
        );



you can skip wrapping object data, which results in simpler data structures:



        my $project = $redminer->createProject({
                identifier => some-id,
                name       => Some Name,
        });
        # $project contains something like
        # { id => 42, identifier => some-id, name => Some Name ... }



Please note that wrapping can be skipped only while operating on single objects, i.e. this flag is honored for create* and update* requests as well as for getting individual objects. This flag is ignored for delete* calls and calls like issues.

    error

Error during the last call. This is an empty string for successfull calls, otherwise it contains an HTTP status line.

If the call failed before sending an actual request (e.g. method name could not be dispatched into an HTTP request), contains description of the client error.

    errorDetails

Contains detailed error messages from the last call. This is an empty hash reference for successfull calls, otherwise please see http://www.redmine.org/projects/redmine/wiki/Rest_api#Validation-errors.

If the call failed before sending an actual request (e.g. method name could not be dispatched into an HTTP request), return value is



        {
                client_error => 1
        }



SEE ALSO

Redmine::API (https://metacpan.org/pod/Redmine::API). Major differences between this module and Redmine::API are:
o <B>DependenciesB>. Redmine::API depends on Moo and REST::Client which in turn depends on LWP::UserAgent, URI and possibly others. WebService::Redmine uses pure Perl OOP and depends directly on LWP::UserAgent and URI.
o <B>Call conventionsB>. Although both modules use dynamic dispatching for building actual HTTP requests, they do it in a different manner. In particular, WebService::Redmine tries to dispatch a single method name without using chains of interrim objects as Redmine::API does.
Fork this project on GitHub: https://github.com/igelhaus/redminer

AUTHOR

Anton Soldatov, <igelhaus@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Anton Soldatov

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 WEBSERVICE::REDMINE (3) 2014-04-14

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.