JIRA::REST - Thin wrapper around JIRA's REST API
version 0.006
use JIRA::REST; my $jira = JIRA::REST->new('https://jira.example.net', 'myuser', 'mypass'); # File a bug my $issue = $jira->POST('/issue', undef, { fields => { project => { key => 'PRJ' }, issuetype => { name => 'Bug' }, summary => 'Cannot login', description => 'Bla bla bla', }, }); # Get issue $issue = $jira->GET("/issue/TST-101"); # Iterate on issues my $search = $jira->POST('/search', undef, { jql => 'project = "TST" and status = "open"', startAt => 0, maxResults => 16, fields => [ qw/summary status assignee/ ], }); foreach my $issue (@{$search->{issues}}) { print "Found issue $issue->{key}\n"; } # Iterate using utility methods $jira->set_search_iterator({ jql => 'project = "TST" and status = "open"', maxResults => 16, fields => [ qw/summary status assignee/ ], }); while (my $issue = $jira->next_issue) { print "Found issue $issue->{key}\n"; }
JIRA is a proprietary bug tracking system from Atlassian.
This module implements a very thin wrapper around JIRA's REST API which is superseding it's old SOAP API for which there is another Perl module called JIRA::Client.
The constructor needs up to four arguments:
URL
A string or a URI object denoting the base URL of the JIRA server. This is a required argument.
You may choose a specific API version by appending the /rest/api/VERSION string to the URL's path. It's more common to left it unspecified, in which case the /rest/api/latest string is appended automatically to the URL.
/rest/api/VERSION
/rest/api/latest
USERNAME
The username of a JIRA user.
It can be undefined if PASSWORD is also undefined. In such a case the user credentials are looked up in the .netrc file.
.netrc
PASSWORD
The HTTP password of the user. (This is the password the user uses to log in to JIRA's web interface.)
It can be undefined, in which case the user credentials are looked up in the .netrc file.
REST_CLIENT_CONFIG
A JIRA::REST object uses a REST::Client object to make the REST invocations. This optional argument must be a hash-ref that can be fed to the REST::Client constructor. Note that the URL argument overwrites any value associated with the host key in this hash.
host
JIRA's REST API documentation lists dozens of "resources" which can be operated via the standard HTTP requests: GET, DELETE, PUT, and POST. JIRA::REST objects implement four methods called GET, DELETE, PUT, and POST to make it easier to invoke and get results from JIRA's REST endpoints.
All four methods need two arguments:
RESOURCE
This is the resource's 'path', minus the API version prefix. For example, in order to GET the list of all fields, you must pass simply /field, not /rest/api/latest/field, and in order to get a list of all the components of a project, you must pass simply /project/$key/components, not /rest/api/latest/project/$key/components.
/field
/rest/api/latest/field
/project/$key/components
/rest/api/latest/project/$key/components
This argument is required.
QUERY
Some resource methods require or admit parameters which are passed as a query-string appended to the resource's path. You may construct the query string and append it to the RESOURCE argument yourself, but it's easier and safer to pass the arguments in a hash. This way the query string is constructed for you and its values are properly percent-encoded to avoid errors.
query-string
This argument is optional for GET and DELETE. For PUT and POST it must be passed explicitly as undef if not needed.
undef
The PUT and POST methods accept two more arguments:
VALUE
This is the "entity" being PUT or POSTed. It can be any value, but usually is a hash-ref. The value is encoded as a JSON string using the JSON::encode method and sent with a Content-Type of application/json.
JSON::encode
application/json
It's usually easy to infer from the JIRA REST API documentation which kind of value you should pass to each resource.
HEADERS
This optional argument allows you to specify extra HTTP headers that should be sent with the request. Each header is specified as a key/value pair in a hash.
All four methods return the value returned by the associated resource's method, as specified in the documentation, decoded according to its content type as follows:
The majority of the API's resources return JSON values. Those are decoded using the decode method of a JSON object. Most of the endpoints return hashes, which are returned as a Perl hash-ref.
decode
JSON
text/plain
Those values are returned as simple strings.
Some endpoints don't return anything. In those cases, the methods return undef. The methods croak if they get any other type of values in return.
In case of errors (i.e., if the underlying HTTP method return an error code different from 2xx) the methods croak with a multi-line string like this:
ERROR: <CODE> - <MESSAGE> <CONTENT-TYPE> <CONTENT>
So, in order to treat errors you must invoke the methods in an eval block or use any of the exception handling Perl modules, such as Try::Tiny and Try::Catch.
Try::Tiny
Try::Catch
Returns the RESOURCE as a Perl data structure.
Deletes the RESOURCE.
Creates RESOURCE based on VALUE.
Updates RESOURCE based on VALUE.
This module provides a few utility methods.
Sets up an iterator for the search specified by the hash-ref PARAMS. It must be called before calls to next_issue.
PARAMS must conform with the query parameters allowed for the /rest/api/2/search JIRA REST endpoint. It may specify a maxResults parameter. If not, a default of 256 will be used.
/rest/api/2/search
maxResults
This must be called after a call to set_search_iterator. Each call returns a reference to the next issue from the filter. When there are no more issues it returns undef.
Using the set_search_iterator/next_issue utility methods you can iterate through large sets of issues without worrying about the startAt/total/offset attributes in the response from the /search REST endpoint. These methods implement the "paging" algorithm needed to work with those attributes.
REST::Client
JIRA::REST uses a REST::Client object to perform the low-level interactions.
JIRA::Client
JIRA::Client is another Perl module implementing the other JIRA API based on SOAP.
JIRA::Client::REST
This is another module implementing JIRA's REST API using SPORE. I got a message from the author saying that he doesn't intend to keep it going.
https://github.com/gnustavo/JIRA-REST
Gustavo L. de M. Chaves <gnustavo@cpan.org>
This software is copyright (c) 2014 by CPqD <www.cpqd.com.br>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install JIRA::REST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JIRA::REST
CPAN shell
perl -MCPAN -e shell install JIRA::REST
For more information on module installation, please visit the detailed CPAN module installation guide.