Redmine

h1. Using the REST API with Perl

The followings are Perl scripts that demonstrate how to use the Redmine REST API.  They guess file encodings from the locale environment variables. See "open":http://perldoc.perl.org/open.html for more details.

h2. GET

<pre><code class="perl">

#!/usr/bin/perl

#	restget : GET a representation of a REST resource

use strict;

use warnings;

use Getopt::Std;

use LWP::UserAgent;

use JSON;

use open ':locale';	# probe the locale environment variables like LANG

sub HELP_MESSAGE {

    print STDERR <<"EOM";

usage : $0 [-p] [-k API_KEY] url

        -p: pretty print

        -k API_KEY: API Access Key

EOM

    exit 0;

}

our ($opt_p, $opt_k);

getopts('pk:') or HELP_MESSAGE();

my $url = shift;

HELP_MESSAGE() unless $url;

#################################################

my $ua = new LWP::UserAgent;

$ua->timeout(10);	# default: 180sec

$ua->ssl_opts( verify_hostname => 0 );	# skip hostname verification

$ua->default_header('X-Redmine-API-Key' => $opt_k) if $opt_k;

my $res = $ua->get($url);

die $res->message if $res->is_error;

my $content =  $res->content;

utf8::decode($content);	# convert UTF-8 binary to text

if ($opt_p) {		# pretty print

    my $perl_ref = from_json($content);

    print to_json($perl_ref, {pretty=>1});

} else {

    print $content, "\n";

}

exit 0;

</code></pre>

Note:

<pre><code>

    my $perl_ref = from_json($content);

</code></pre>

Here a "Perl reference":http://perldoc.perl.org/perlref.html" @$perl_ref@ is a reference to a whole data structure parsed.

Usage examples:

<pre><code>

./restget http://www.redmine.org/issues/22097.json

./restget -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/issues/117594.json

</code></pre>

The next commands put a textile table into the clipboard.

<pre><code>

./restget http://www.redmine.org/projects/redmine/versions.json | perl -MJSON -nle 'for $v (sort{$a->{name} cmp $b->{name}}@{decode_json($_)->{versions}}){$d=$v->{description};print qq/|version:"$v->{name}"|$d|/ if $d}' > /dev/clipboard

</code></pre>

You can paste it on your Wiki page as follows.

|version:"0.7.1"|Bug fix release|

|version:"0.7.2"|Bug fix release|

|version:"0.7.3"|Security+Bug fix release|

|version:"0.9.0"|0.9 release candidate 1|

|version:"0.9.6"|Security release|

|version:"1.0.1"|Bug fixes for the 1.0.0 RC - (Estimated release date)|

|version:"1.2.3"|Bug fix release for the 1.2.x serie|

|version:"1.3.1"|Maintenance release|

|version:"1.4.3"|Maintenance release|

|version:"1.4.7"|security release|

|version:"2.0.2"|Maintenance release|

|version:"2.6.10"|For Rails 3.2 due to JRuby Nokogiri/Loofah does not support Rails 4.2|

|version:"Candidate for next major release"|Features that the contributors would like to add in the next major version|

|version:"Candidate for next minor release"|Fixes that the contributors would like to add in the next minor version|

|version:"Unplanned"|Features that the core contributors of Redmine would like to add in a future version|

h2. PUT

<pre><code class="perl">

#!/usr/bin/perl

#	restput : PUT a representation of a REST resource

use strict;

use warnings;

use Getopt::Std;

use LWP::UserAgent;

use open ':locale';	# probe the locale environment variables like LANG

sub HELP_MESSAGE {

    print STDERR <<"EOM";

usage : $0 [-p API_KEY] url [files...]

        -k API_KEY: API Access Key

EOM

    exit 0;

}

our ($opt_k);

getopts('k:') or HELP_MESSAGE();

my $url = shift;

HELP_MESSAGE() unless $url;

#################################################

my $ua = new LWP::UserAgent;

$ua->timeout(10);	# default: 180sec

$ua->ssl_opts( verify_hostname => 0 );	# skip hostname verification

$ua->default_header('X-Redmine-API-Key' => $opt_k) if $opt_k;

my $content;

{

    local $/;

    $content = <>;	# gets whole input

}

utf8::encode($content);	# convert UTF-8 binary to text

my $res = $ua->put($url,

                   'Content-Type' => 'application/json;charset=utf-8',

                   'Content' => $content);

die $res->message if $res->is_error;

print $res->content();

exit 0;

</code></pre>

Usage examples:

<pre><code>

# change my name

echo '{"user":{"firstname":"James","lastname":"Bond"}}' | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/users/current.json

</code></pre>

The following script converts a Wiki content to JSON format.

<pre><code class="perl">

#!/usr/bin/perl

#	restwiki : convert a Wiki content to JSON format

use strict;

use warnings;

use Getopt::Std;

use JSON;

use open ':locale';

sub HELP_MESSAGE {

    print STDERR <<"EOM";

usage :    $0 [-c comment] [files...]

    -c : comment

EOM

    exit 0;

}

our ($opt_c);

getopts('c:') or HELP_MESSAGE();

#################################################

my $ref;

{

    local $/;	# enable slurp mode

    $ref->{wiki_page}->{text} = <>;

}

$ref->{wiki_page}->{comments} = $opt_c if $opt_c;

print to_json($ref);

exit 0;

</code></pre>

The following commands create or update a Wiki page "Test Page".

<pre><code>

./restwiki foo | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://my.redmine.local/projects/test-project/wiki/Test_Page.json

</code></pre>

You, a one-liner, may want to do as follows;

<pre><code>

perl -MJSON -e 'local $/;$ref->{wiki_page}->{text} = <>;print to_json($ref)' foo | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://my.redmine.local/projects/test-project/wiki/Test_Page.json

</code></pre>

h2. Resources

* "LWP::UserAgent":http://search.cpan.org/~ether/libwww-perl-6.15/lib/LWP/UserAgent.pm

* "JSON":http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

* "perlref - Perl references and nested data structures":http://perldoc.perl.org/perlref.html

* "perlunitut - Perl Unicode Tutorial":http://perldoc.perl.org/perlunitut.html