.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "JIRA::REST 3pm"
.TH JIRA::REST 3pm "2018-07-29" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JIRA::REST \- Thin wrapper around Jira's REST API
.SH "VERSION"
.IX Header "VERSION"
version 0.019
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use JIRA::REST;
\&
\&    my $jira = JIRA::REST\->new({
\&        URL      => \*(Aqhttps://jira.example.net\*(Aq,
\&        username => \*(Aqmyuser\*(Aq,
\&        password => \*(Aqmypass\*(Aq,
\&    });
\&
\&    # File a bug
\&    my $issue = $jira\->POST(\*(Aq/issue\*(Aq, undef, {
\&        fields => {
\&            project   => { key => \*(AqPRJ\*(Aq },
\&            issuetype => { name => \*(AqBug\*(Aq },
\&            summary   => \*(AqCannot login\*(Aq,
\&            description => \*(AqBla bla bla\*(Aq,
\&        },
\&    });
\&
\&    # Get issue
\&    $issue = $jira\->GET("/issue/TST\-101");
\&
\&    # Iterate on issues
\&    my $search = $jira\->POST(\*(Aq/search\*(Aq, undef, {
\&        jql        => \*(Aqproject = "TST" and status = "open"\*(Aq,
\&        startAt    => 0,
\&        maxResults => 16,
\&        fields     => [ qw/summary status assignee/ ],
\&    });
\&
\&    foreach my $issue (@{$search\->{issues}}) {
\&        print "Found issue $issue\->{key}\en";
\&    }
\&
\&    # Iterate using utility methods
\&    $jira\->set_search_iterator({
\&        jql        => \*(Aqproject = "TST" and status = "open"\*(Aq,
\&        maxResults => 16,
\&        fields     => [ qw/summary status assignee/ ],
\&    });
\&
\&    while (my $issue = $jira\->next_issue) {
\&        print "Found issue $issue\->{key}\en";
\&    }
\&
\&    # Attach files using an utility method
\&    $jira\->attach_files(\*(AqTST\-123\*(Aq, \*(Aq/path/to/doc.txt\*(Aq, \*(Aqimage.png\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Jira <http://www.atlassian.com/software/jira/> is a proprietary bug
tracking system from Atlassian.
.PP
This module implements a very thin wrapper around Jira's \s-1REST\s0 APIs:
.IP "\(bu" 4
Jira Core \s-1REST API\s0 <https://docs.atlassian.com/jira/REST/server/>
.Sp
This rich \s-1API\s0 superseded the old Jira \s-1SOAP
API\s0 <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.
.Sp
The endpoints of this \s-1API\s0 have a path prefix of \f(CW\*(C`/rest/api/VERSION\*(C'\fR.
.IP "\(bu" 4
Jira Service Desk \s-1REST API\s0 <https://docs.atlassian.com/jira-servicedesk/REST/server/>
.Sp
This \s-1API\s0 deals with the objects of the Jira Service Desk application. Its
endpoints have a path prefix of \f(CW\*(C`/rest/servicedeskapi\*(C'\fR.
.IP "\(bu" 4
Jira Software \s-1REST API\s0 <https://docs.atlassian.com/jira-software/REST/server/>
.Sp
This \s-1API\s0 deals with the objects of the Jira Software application. Its
endpoints have a path prefix of \f(CW\*(C`/rest/agile/VERSION\*(C'\fR.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new \s-1HASHREF\s0"
.IX Subsection "new HASHREF"
.SS "new \s-1URL, USERNAME, PASSWORD, REST_CLIENT_CONFIG, ANONYMOUS, PROXY, SSL_VERIFY_NONE\s0"
.IX Subsection "new URL, USERNAME, PASSWORD, REST_CLIENT_CONFIG, ANONYMOUS, PROXY, SSL_VERIFY_NONE"
The 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.
.PP
The arguments are described below with the names which must be used as the
hash keys:
.IP "\(bu" 4
\&\fBurl\fR
.Sp
A string or a \s-1URI\s0 object denoting the base \s-1URL\s0 of the Jira server. This is a
required argument.
.Sp
The \s-1REST\s0 methods described below all accept as a first argument the
endpoint's path of the specific \s-1API\s0 method to call. In general you can pass
the complete path, beginning with the prefix denoting the particular \s-1API\s0 to
use (\f(CW\*(C`/rest/api/VERSION\*(C'\fR, \f(CW\*(C`/rest/servicedeskapi\*(C'\fR, or
\&\f(CW\*(C`/rest/agile/VERSION\*(C'\fR). However, you may specify a default \s-1API\s0 prefix by
suffixing the \s-1URL\s0 with it. For example:
.Sp
.Vb 5
\&    my $jira = JIRA::REST\->new({
\&        url      => \*(Aqhttps://jira.example.net/jira/rest/api/1\*(Aq,
\&        username => \*(Aqmyuser\*(Aq,
\&        password => \*(Aqmypass\*(Aq
\&    });
\&
\&    $jira\->GET(\*(Aq/rest/api/1/issue/TST\-1\*(Aq);
\&    $jira\->GET(\*(Aq/issue/TST\-1\*(Aq);
.Ve
.Sp
With this constructor call both \s-1GET\s0 methods are the same, because the second
one does not specify an \s-1API\s0 prefix. This is useful if you mainly want to use
a particular \s-1API\s0 or if you want to specify a particular version of an \s-1API\s0
during construction.
.IP "\(bu" 4
\&\fBusername\fR
.IP "\(bu" 4
\&\fBpassword\fR
.Sp
The username and password of a Jira user to use for authentication.
.Sp
If \fBanonymous\fR is false then, if either \fBusername\fR or \fBpassword\fR isn't
defined the module looks them up in either the \f(CW\*(C`.netrc\*(C'\fR file or via
Config::Identity (which allows \f(CW\*(C`gpg\*(C'\fR encrypted credentials).
.Sp
Config::Identity will look for \fI~/.jira\-identity\fR or \fI~/.jira\fR.
You can change the filename stub from \f(CW\*(C`jira\*(C'\fR to a custom stub with the
\&\f(CW\*(C`JIRA_REST_IDENTITY\*(C'\fR environment variable.
.IP "\(bu" 4
\&\fBrest_client_config\fR
.Sp
A \s-1JIRA::REST\s0 object uses a REST::Client object to make the \s-1REST\s0
invocations. This optional argument must be a hash reference that can be fed
to the REST::Client constructor. Note that the \f(CW\*(C`url\*(C'\fR argument
overwrites any value associated with the \f(CW\*(C`host\*(C'\fR key in this hash.
.Sp
As an extension, the hash reference also accepts one additional argument
called \fBproxy\fR 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. Instead, use the following argument instead.
.IP "\(bu" 4
\&\fBproxy\fR
.Sp
To use a network proxy set this argument to the string or \s-1URI\s0 object
describing the fully qualified \s-1URL\s0 (including port) to your network proxy.
.IP "\(bu" 4
\&\fBssl_verify_none\fR
.Sp
Sets the \f(CW\*(C`SSL_verify_mode\*(C'\fR and \f(CW\*(C`verify_hostname ssl\*(C'\fR 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.
.IP "\(bu" 4
\&\fBanonymous\fR
.Sp
Tells the module that you want to connect to the specified Jira server with
no username or password.  This way you can access public Jira servers
without needing to authenticate.
.SH "REST METHODS"
.IX Header "REST METHODS"
Jira's \s-1REST API\s0 documentation lists dozens of \*(L"resources\*(R" which can be
operated via the standard \s-1HTTP\s0 requests: \s-1GET, DELETE, PUT,\s0 and
\&\s-1POST. JIRA::REST\s0 objects implement four methods called \s-1GET, DELETE,
PUT,\s0 and \s-1POST\s0 to make it easier to invoke and get results from Jira's
\&\s-1REST\s0 endpoints.
.PP
All four methods need two arguments:
.IP "\(bu" 4
\&\s-1RESOURCE\s0
.Sp
This is the resource's 'path'. For example, in order to \s-1GET\s0 the list of all
fields, you pass \f(CW\*(C`/rest/api/latest/field\*(C'\fR, and in order to get \s-1SLA\s0
information about an issue you pass
\&\f(CW\*(C`/rest/servicedeskapi/request/$key/sla\*(C'\fR.
.Sp
If you're using a method form Jira Core \s-1REST API\s0 you may omit the prefix
\&\f(CW\*(C`/rest/api/VERSION\*(C'\fR. For example, to \s-1GET\s0 the list of all fields you may
pass just \f(CW\*(C`/field\*(C'\fR.
.Sp
This argument is required.
.IP "\(bu" 4
\&\s-1QUERY\s0
.Sp
Some resource methods require or admit parameters which are passed as
a \f(CW\*(C`query\-string\*(C'\fR appended to the resource's path. You may construct
the query string and append it to the \s-1RESOURCE\s0 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.
.Sp
This argument is optional for \s-1GET\s0 and \s-1DELETE.\s0 For \s-1PUT\s0 and \s-1POST\s0 it must
be passed explicitly as \f(CW\*(C`undef\*(C'\fR if not needed.
.PP
The \s-1PUT\s0 and \s-1POST\s0 methods accept two more arguments:
.IP "\(bu" 4
\&\s-1VALUE\s0
.Sp
This is the \*(L"entity\*(R" being \s-1PUT\s0 or POSTed. It can be any value, but
usually is a hash reference. The value is encoded as a
\&\s-1JSON\s0 <http://www.json.org/> string using the \f(CW\*(C`JSON::encode\*(C'\fR method
and sent with a Content-Type of \f(CW\*(C`application/json\*(C'\fR.
.Sp
It's usually easy to infer from the Jira \s-1REST API\s0 documentation which
kind of value you should pass to each resource.
.Sp
This argument is required.
.IP "\(bu" 4
\&\s-1HEADERS\s0
.Sp
This optional argument allows you to specify extra \s-1HTTP\s0 headers that
should be sent with the request. Each header is specified as a
key/value pair in a hash.
.PP
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:
.IP "\(bu" 4
application/json
.Sp
The majority of the \s-1API\s0's resources return \s-1JSON\s0 values. Those are
decoded using the \f(CW\*(C`decode\*(C'\fR method of a \f(CW\*(C`JSON\*(C'\fR object. Most of the
endpoints return hashes, which are returned as a Perl hash reference.
.IP "\(bu" 4
text/plain
.Sp
Those values are returned as simple strings.
.PP
Some endpoints don't return anything. In those cases, the methods
return \f(CW\*(C`undef\*(C'\fR. The methods croak if they get any other type of
values in return.
.PP
In case of errors (i.e., if the underlying \s-1HTTP\s0 method return an error
code different from 2xx) the methods croak with a multi-line string
like this:
.PP
.Vb 3
\&    ERROR: <CODE> \- <MESSAGE>
\&    <CONTENT\-TYPE>
\&    <CONTENT>
.Ve
.PP
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
\&\f(CW\*(C`Try::Tiny\*(C'\fR and \f(CW\*(C`Try::Catch\*(C'\fR.
.SS "\s-1GET RESOURCE\s0 [, \s-1QUERY\s0]"
.IX Subsection "GET RESOURCE [, QUERY]"
Returns the \s-1RESOURCE\s0 as a Perl data structure.
.SS "\s-1DELETE RESOURCE\s0 [, \s-1QUERY\s0]"
.IX Subsection "DELETE RESOURCE [, QUERY]"
Deletes the \s-1RESOURCE.\s0
.SS "\s-1PUT RESOURCE, QUERY, VALUE\s0 [, \s-1HEADERS\s0]"
.IX Subsection "PUT RESOURCE, QUERY, VALUE [, HEADERS]"
Creates \s-1RESOURCE\s0 based on \s-1VALUE.\s0
.SS "\s-1POST RESOURCE, QUERY, VALUE\s0 [, \s-1HEADERS\s0]"
.IX Subsection "POST RESOURCE, QUERY, VALUE [, HEADERS]"
Updates \s-1RESOURCE\s0 based on \s-1VALUE.\s0
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
This module provides a few utility methods.
.SS "\fBset_search_iterator\fP \s-1PARAMS\s0"
.IX Subsection "set_search_iterator PARAMS"
Sets up an iterator for the search specified by the hash reference \s-1PARAMS.\s0
It must be called before calls to \fBnext_issue\fR.
.PP
\&\s-1PARAMS\s0 must conform with the query parameters allowed for the
\&\f(CW\*(C`/rest/api/2/search\*(C'\fR Jira \s-1REST\s0 endpoint.
.SS "\fBnext_issue\fP"
.IX Subsection "next_issue"
This must be called after a call to \fBset_search_iterator\fR. Each call
returns a reference to the next issue from the filter. When there are no
more issues it returns undef.
.PP
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 \s-1REST\s0 endpoint. These methods
implement the \*(L"paging\*(R" algorithm needed to work with those attributes.
.SS "\fBattach_files\fP \s-1ISSUE FILE...\s0"
.IX Subsection "attach_files ISSUE FILE..."
The \f(CW\*(C`/issue/KEY/attachments\*(C'\fR \s-1REST\s0 endpoint, used to attach files to issues,
requires a specific content type encoding which is difficult to come up with
just the \f(CW\*(C`REST::Client\*(C'\fR interface. This utility method offers an easier
interface to attach files to issues.
.SH "PERL AND JIRA COMPATIBILITY POLICY"
.IX Header "PERL AND JIRA COMPATIBILITY POLICY"
Currently \s-1JIRA::REST\s0 requires Perl 5.10 and supports Jira 7.0.
.PP
We try to be compatible with the Perl native packages of the oldest Ubuntu
\&\s-1LTS\s0 <https://www.ubuntu.com/info/release-end-of-life> and
CentOS <https://wiki.centos.org/About/Product> Linux distributions still
getting maintainance updates.
.PP
.Vb 9
\&  +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  | Distro                | Perl | End of Life |
\&  +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&  | Ubuntu 14.04 (trusty) | 5.18 |   2019\-04   |
\&  | Ubuntu 16.04 (xenial) | 5.22 |   2021\-04   |
\&  | Ubuntu 18.04 (bionic) | 5.26 |   2023\-04   |
\&  | CentOS 6              | 5.10 |   2020\-12   |
\&  | CentOS 7              | 5.16 |   2024\-07   |
\&  +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
As you can see, we're kept behind mostly by the slow pace of CentOS (actually,
\&\s-1RHEL\s0) releases.
.PP
As for Jira, the policy is very lax. I (the author) only test \s-1JIRA::REST\s0 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
\&\f(CW\*(C`REST::Client\*(C'\fR
.Sp
\&\s-1JIRA::REST\s0 uses a REST::Client object to perform the low-level interactions.
.IP "\(bu" 4
\&\f(CW\*(C`JIRA::Client::REST\*(C'\fR
.Sp
This is another module implementing Jira's \s-1REST API\s0 using
\&\s-1SPORE\s0 <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.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/gnustavo/JIRA\-REST>
.SH "AUTHOR"
.IX Header "AUTHOR"
Gustavo L. de M. Chaves <gnustavo@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2018 by CPqD <www.cpqd.com.br>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.