|
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
|