Project

General

Profile

Patch #22097 ยป Rest_api_with_perl.txt

Hiroo Hayashi, 2016-02-20 14:06

 
1
h1. Using the REST API with Perl
2

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

    
5
h2. GET
6

    
7
<pre><code class="perl">
8
#!/usr/bin/perl
9
#	restget : GET a representation of a REST resource
10
use strict;
11
use warnings;
12
use Getopt::Std;
13
use LWP::UserAgent;
14
use JSON;
15
use open ':locale';	# probe the locale environment variables like LANG
16

    
17
sub HELP_MESSAGE {
18
    print STDERR <<"EOM";
19
usage : $0 [-p] [-k API_KEY] url
20
        -p: pretty print
21
        -k API_KEY: API Access Key
22
EOM
23
    exit 0;
24
}
25
our ($opt_p, $opt_k);
26
getopts('pk:') or HELP_MESSAGE();
27
my $url = shift;
28
HELP_MESSAGE() unless $url;
29
#################################################
30
my $ua = new LWP::UserAgent;
31
$ua->timeout(10);	# default: 180sec
32
$ua->ssl_opts( verify_hostname => 0 );	# skip hostname verification
33
$ua->default_header('X-Redmine-API-Key' => $opt_k) if $opt_k;
34

    
35
my $res = $ua->get($url);
36
die $res->message if $res->is_error;
37

    
38
my $content =  $res->content;
39
utf8::decode($content);	# convert UTF-8 binary to text
40
if ($opt_p) {		# pretty print
41
    my $perl_ref = from_json($content);
42
    print to_json($perl_ref, {pretty=>1});
43
} else {
44
    print $content, "\n";
45
}
46
exit 0;
47
</code></pre>
48

    
49
Note:
50

    
51
<pre><code>
52
    my $perl_ref = from_json($content);
53
</code></pre>
54

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

    
57
Usage examples:
58

    
59
<pre><code>
60
./restget http://www.redmine.org/issues/22097.json
61
./restget -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/issues/117594.json
62
</code></pre>
63

    
64
The next commands put a textile table into the clipboard.
65

    
66
<pre><code>
67
./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
68
</code></pre>
69

    
70
You can paste it on your Wiki page as follows.
71

    
72
|version:"0.7.1"|Bug fix release|
73
|version:"0.7.2"|Bug fix release|
74
|version:"0.7.3"|Security+Bug fix release|
75
|version:"0.9.0"|0.9 release candidate 1|
76
|version:"0.9.6"|Security release|
77
|version:"1.0.1"|Bug fixes for the 1.0.0 RC - (Estimated release date)|
78
|version:"1.2.3"|Bug fix release for the 1.2.x serie|
79
|version:"1.3.1"|Maintenance release|
80
|version:"1.4.3"|Maintenance release|
81
|version:"1.4.7"|security release|
82
|version:"2.0.2"|Maintenance release|
83
|version:"2.6.10"|For Rails 3.2 due to JRuby Nokogiri/Loofah does not support Rails 4.2|
84
|version:"Candidate for next major release"|Features that the contributors would like to add in the next major version|
85
|version:"Candidate for next minor release"|Fixes that the contributors would like to add in the next minor version|
86
|version:"Unplanned"|Features that the core contributors of Redmine would like to add in a future version|
87

    
88
h2. PUT
89

    
90
<pre><code class="perl">
91
#!/usr/bin/perl
92
#	restput : PUT a representation of a REST resource
93
use strict;
94
use warnings;
95
use Getopt::Std;
96
use LWP::UserAgent;
97
use open ':locale';	# probe the locale environment variables like LANG
98

    
99
sub HELP_MESSAGE {
100
    print STDERR <<"EOM";
101
usage : $0 [-p API_KEY] url [files...]
102
        -k API_KEY: API Access Key
103
EOM
104
    exit 0;
105
}
106
our ($opt_k);
107
getopts('k:') or HELP_MESSAGE();
108
my $url = shift;
109
HELP_MESSAGE() unless $url;
110
#################################################
111
my $ua = new LWP::UserAgent;
112
$ua->timeout(10);	# default: 180sec
113
$ua->ssl_opts( verify_hostname => 0 );	# skip hostname verification
114
$ua->default_header('X-Redmine-API-Key' => $opt_k) if $opt_k;
115

    
116
my $content;
117
{
118
    local $/;
119
    $content = <>;	# gets whole input
120
}
121
utf8::encode($content);	# convert UTF-8 binary to text
122
my $res = $ua->put($url,
123
                   'Content-Type' => 'application/json;charset=utf-8',
124
                   'Content' => $content);
125
die $res->message if $res->is_error;
126
print $res->content();
127
exit 0;
128
</code></pre>
129

    
130
Usage examples:
131

    
132
<pre><code>
133
# change my name
134
echo '{"user":{"firstname":"James","lastname":"Bond"}}' | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://demo.redmine.org/users/current.json
135
</code></pre>
136

    
137
The following script converts a Wiki content to JSON format.
138

    
139
<pre><code class="perl">
140
#!/usr/bin/perl
141
#	restwiki : convert a Wiki content to JSON format
142
use strict;
143
use warnings;
144
use Getopt::Std;
145
use JSON;
146
use open ':locale';
147

    
148
sub HELP_MESSAGE {
149
    print STDERR <<"EOM";
150
usage :    $0 [-c comment] [files...]
151
    -c : comment
152
EOM
153
    exit 0;
154
}
155
our ($opt_c);
156
getopts('c:') or HELP_MESSAGE();
157
#################################################
158
my $ref;
159
{
160
    local $/;	# enable slurp mode
161
    $ref->{wiki_page}->{text} = <>;
162
}
163
$ref->{wiki_page}->{comments} = $opt_c if $opt_c;
164
print to_json($ref);
165
exit 0;
166
</code></pre>
167

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

    
170
<pre><code>
171
./restwiki foo | ./restput -k 57acc39afc967564aa79a6bd329897d7040a9bc8 http://my.redmine.local/projects/test-project/wiki/Test_Page.json
172
</code></pre>
173

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

    
176
<pre><code>
177
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
178
</code></pre>
179

    
180
h2. Resources
181

    
182
* "LWP::UserAgent":http://search.cpan.org/~ether/libwww-perl-6.15/lib/LWP/UserAgent.pm
183
* "JSON":http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm
184
* "perlref - Perl references and nested data structures":http://perldoc.perl.org/perlref.html
185
* "perlunitut - Perl Unicode Tutorial":http://perldoc.perl.org/perlunitut.html
    (1-1/1)