h1. Using the REST API with Perl The followings are Perl scripts that demonstrate how to use the Redmine REST API. h2. GET
#!/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;
Note:
my $perl_ref = from_json($content);
Here a "Perl reference":http://perldoc.perl.org/perlref.html" @$perl_ref@ is a reference to a whole data structure parsed.
Usage examples:
./restget http://www.redmine.org/issues/22097.json
./restget -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/issues/117594.json
The next commands put a textile table into the clipboard.
./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
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
#!/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;
Usage examples:
# change my name
echo '{"user":{"firstname":"James","lastname":"Bond"}}' | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/users/current.json
The following script converts a Wiki content to JSON format.
#!/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;
The following commands create or update a Wiki page "Test Page".
./restwiki foo | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://my.redmine.local/projects/test-project/wiki/Test_Page.json
You, a one-liner, may want to do as follows;
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
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