view release on metacpan or  search on metacpan

lib/JIRA/REST.pm  view on Meta::CPAN

endpoints have a path prefix of C</rest/servicedeskapi>.

=item * L<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 C</rest/agile/VERSION>.

=back

=head1 CONSTRUCTORS

=head2 new HASHREF

=head2 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:

=over 4

=item * B<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 (C</rest/api/VERSION>, C</rest/servicedeskapi>, or
C</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.

=item * B<username>

=item * B<password>

The username and password of a Jira user to use for authentication.

If B<anonymous> is false and no B<pat> given, then, if either B<username> or
B<password> isn't defined the module looks them up in either the C<.netrc> file
or via L<Config::Identity> (which allows C<gpg> encrypted credentials).

L<Config::Identity> will look for F<~/.jira-identity> or F<~/.jira>.
You can change the filename stub from C<jira> to a custom stub with the
C<JIRA_REST_IDENTITY> environment variable.

=item * B<rest_client_config>

A JIRA::REST object uses a L<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 C<url> argument
overwrites any value associated with the C<host> key in this hash.

As an extension, the hash reference also accepts one additional argument
called B<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.

=item * B<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.

=item * B<ssl_verify_none>

Sets the C<SSL_verify_mode> and C<verify_hostname ssl> options on the
underlying L<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 L<LWP::UserAgent>'s verification methods.

=item * B<anonymous>

=item * B<pat>

=item * B<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 B<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 B<username> and B<password>
arguments are disregarded.

The B<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
L<https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html>
for details. If enabled, the B<username> and B<password> arguments are
disregarded.

The booleal B<session> argument tells the module if you want it to acquire a
session cookie by making a C<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 C<DELETE
/rest/auth/1/session> call to logout from Jira. If enabled, the B<username> and
B<password> arguments are required.

=back