Provided by: libjira-rest-perl_0.023-1_all 
NAME
JIRA::REST - Thin wrapper around Jira's REST API
VERSION
version 0.023
SYNOPSIS
use JIRA::REST;
my $jira = JIRA::REST->new({
url => 'https://jira.example.net',
username => 'myuser',
password => 'mypass',
});
my $jira_with_session = JIRA::REST->new({
url => 'https://jira.example.net',
username => 'myuser',
password => 'mypass',
session => 1,
});
my $jira_with_pat = JIRA::REST->new({
url => 'https://jira.example.net',
pat => 'NDc4NDkyNDg3ODE3OstHYSeYC1GnuqRacSqvUbookcZk',
});
my $jira_anonymous = JIRA::REST->new({
url => 'https://jira.example.net',
anonymous => 1,
});
# 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";
}
# Attach files using an utility method
$jira->attach_files('TST-123', '/path/to/doc.txt', 'image.png');
DESCRIPTION
Jira <http://www.atlassian.com/software/jira/> is a proprietary bug tracking system from
Atlassian.
This module implements a very thin wrapper around Jira's REST APIs:
• Jira Core REST API <https://docs.atlassian.com/software/jira/docs/api/REST/latest/>
This rich API superseded the old Jira SOAP API
<http://docs.atlassian.com/software/jira/docs/api/rpc-jira-
plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html> which isn't supported
anymore as of Jira version 7.
The endpoints of this API have a path prefix of "/rest/api/VERSION".
• Jira Service Desk REST API <https://docs.atlassian.com/jira-servicedesk/REST/server/>
This API deals with the objects of the Jira Service Desk application. Its endpoints
have a path prefix of "/rest/servicedeskapi".
• Jira Software REST API <https://docs.atlassian.com/jira-software/REST/server/>
This API deals with the objects of the Jira Software application. Its endpoints have a
path prefix of "/rest/agile/VERSION".
CONSTRUCTORS
new HASHREF
new URL, USERNAME, PASSWORD, REST_CLIENT_CONFIG, PROXY, SSL_VERIFY_NONE, ANONYMOUS, PAT,
SESSION
The default constructor can take its arguments from a single hash reference or from a list
of positional parameters. The first form is preferred because it lets you specify only the
arguments you need. The second form forces you to pass undefined values if you need to
pass a specific value to an argument further to the right.
The arguments are described below with the names which must be used as the hash keys:
• url
A string or a URI object denoting the base URL of the Jira server. This is a required
argument.
The REST methods described below all accept as a first argument the endpoint's path of
the specific API method to call. In general you can pass the complete path, beginning
with the prefix denoting the particular API to use ("/rest/api/VERSION",
"/rest/servicedeskapi", or "/rest/agile/VERSION"). However, you may specify a default
API prefix by suffixing the URL with it. For example:
my $jira = JIRA::REST->new({
url => 'https://jira.example.net/jira/rest/api/1',
username => 'myuser',
password => 'mypass'
});
$jira->GET('/rest/api/1/issue/TST-1');
$jira->GET('/issue/TST-1');
With this constructor call both GET methods are the same, because the second one does
not specify an API prefix. This is useful if you mainly want to use a particular API
or if you want to specify a particular version of an API during construction.
• username
• password
The username and password of a Jira user to use for authentication.
If anonymous is false and no pat given, then, if either username or password isn't
defined the module looks them up in either the ".netrc" file or via Config::Identity
(which allows "gpg" encrypted credentials).
Config::Identity will look for ~/.jira-identity or ~/.jira. You can change the
filename stub from "jira" to a custom stub with the "JIRA_REST_IDENTITY" environment
variable.
• rest_client_config
A JIRA::REST object uses a REST::Client object to make the REST invocations. This
optional argument must be a hash reference 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.
As an extension, the hash reference also accepts one additional argument called proxy
that is an extension to the REST::Client configuration and will be removed from the
hash before passing it on to the REST::Client constructor. However, this argument is
deprecated since v0.017 and you should avoid it. Use the following argument instead.
• proxy
To use a network proxy set this argument to the string or URI object describing the
fully qualified URL (including port) to your network proxy.
• ssl_verify_none
Sets the "SSL_verify_mode" and "verify_hostname ssl" options on the underlying
REST::Client's user agent to 0, thus disabling them. This allows access to Jira
servers that have self-signed certificates that don't pass LWP::UserAgent's
verification methods.
• anonymous
• pat
• session
These three arguments are mutually exclusive, i.e., you can use at most one of them.
By default, they are all undefined.
The boolean anonymous argument tells the module if you want to connect to the
specified Jira with no authentication. This allows you to get some information from
open or public Jira servers. If enabled, the username and password arguments are
disregarded.
The pat argument maps to a string which should be a personal access token that can be
used for authentication instead of a username and a password. This option is
available since Jira version 8.14. Please refer to
<https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html>
for details. If enabled, the username and password arguments are disregarded.
The booleal session argument tells the module if you want it to acquire a session
cookie by making a "POST /rest/auth/1/session" call to login to Jira. This is
particularly useful when interacting with Jira Data Center, because it can use the
session cookie to maintain affinity with one of the redundant servers. Upon
destruction, the object makes a "DELETE /rest/auth/1/session" call to logout from
Jira. If enabled, the username and password arguments are required.
new_session OPTIONS
This alternative constructor simply invokes the default constructor with the same options,
adding to them the session option. New code should use the default constructor with the
session option because this constructor may be deprecated in the future.
REST METHODS
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'. For example, in order to GET the list of all fields,
you pass "/rest/api/latest/field", and in order to get SLA information about an issue
you pass "/rest/servicedeskapi/request/$key/sla".
If you're using a method from Jira Core REST API you may omit the prefix
"/rest/api/VERSION". For example, to GET the list of all fields you may pass just
"/field".
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 <http://en.wikipedia.org/wiki/Percent-encoding> to avoid errors.
This argument is optional for GET and DELETE. For PUT and POST it must be passed
explicitly as "undef" if not needed.
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
reference. The value is encoded as a JSON <http://www.json.org/> string using the
"JSON::encode" method and sent with a Content-Type of "application/json".
It's usually easy to infer from the Jira REST API documentation which kind of value
you should pass to each resource.
This argument is required.
• 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:
• application/json
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 reference.
• 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".
GET RESOURCE [, QUERY]
Returns the RESOURCE as a Perl data structure.
DELETE RESOURCE [, QUERY]
Deletes the RESOURCE.
PUT RESOURCE, QUERY, VALUE [, HEADERS]
Creates RESOURCE based on VALUE.
POST RESOURCE, QUERY, VALUE [, HEADERS]
Updates RESOURCE based on VALUE.
UTILITY METHODS
This module provides a few utility methods.
rest_client
Returns the REST::Client object used to interact with Jira. It may be useful when the Jira
API isn't enough and you have to go deeper.
set_search_iterator PARAMS
Sets up an iterator for the search specified by the hash reference 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.
next_issue
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.
attach_files ISSUE FILE...
The "/issue/KEY/attachments" REST endpoint, used to attach files to issues, requires a
specific content type encoding which is difficult to come up with just the "REST::Client"
interface. This utility method offers an easier interface to attach files to issues.
PERL AND JIRA COMPATIBILITY POLICY
Currently JIRA::REST requires Perl 5.16 and is tested on Jira Data Center 8.13.
We try to be compatible with the Perl native packages of the oldest Ubuntu LTS
<https://www.ubuntu.com/info/release-end-of-life> and CentOS
<https://wiki.centos.org/About/Product> Linux distributions still getting maintainance
updates.
+-------------+-----------------------+------+
| End of Life | Distro | Perl |
+-------------+-----------------------+------+
| 2023-04 | Ubuntu 18.04 (bionic) | 5.26 |
| 2024-07 | CentOS 7 | 5.16 |
| 2025-04 | Ubuntu 20.04 (focal) | 5.30 |
| 2027-04 | Ubuntu 22.04 (jammy) | 5.34 |
| 2029-05 | CentOS 8 | 5.26 |
+-------------+-----------------------+------+
As you can see, we're kept behind mostly by the slow pace of CentOS (actually, RHEL)
releases.
As for Jira, the policy is very lax. I (the author) only test JIRA::REST on the Jira
server installed in the company I work for, which is usually (but not always) at most one
year older than the newest released version. I don't have yet an easy way to test it on
different versions.
SEE ALSO
• "REST::Client"
JIRA::REST uses a REST::Client object to perform the low-level interactions.
• "JIRA::REST::OAuth"
This module Sub Classes JIRA::REST providing OAuth 1.0 support.
• "JIRA::Client::REST"
This is another module implementing Jira's REST API using SPORE
<https://github.com/SPORE/specifications/blob/master/spore_description.pod>. I got a
message from the author saying that he doesn't intend to keep it going.
REPOSITORY
<https://github.com/gnustavo/JIRA-REST>
AUTHOR
Gustavo L. de M. Chaves <gnustavo@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2022 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.