h1. Using the REST API with Perl

The followings are Perl scripts that demonstrate how to use the Redmine REST API.

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