view release on metacpan or  search on metacpan

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

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<anonymous>

The boolean B<anonymous> authentication 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, no other
authentication arguments below are used.

=item * B<pat>

The B<pat> authentication argument is a string representing a L<Personal Access
Token|https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html>
that can be used for authentication.  Personal Access Tokens are available since
Jira 8.14. If enabled, no other authentication arguments below are used.

=item * B<client_id>

=item * B<client_secret>

=item * B<scope>

These authentication arguments are strings used to request an Access Token for a
L<service
account|https://confluence.atlassian.com/enterprise/service-accounts-overview-1627095923.html>>

If B<client_id> is set, the other two arguments must also be set. Service
Account Access Tokens are available since Jira 11.0.

If enabled, no other authentication arguments below are used.

=item * B<username>

=item * B<password>

The B<username> and B<password> authentication arguments are strings
representing the usual credentials of a user. They are used as the default
authentication method if no other method above is defined. JIRA::REST uses Basic
HTTP authentication in this case.

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<session>

The boolean 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.

This option is used only if the B<username> and B<password> arguments are also
used.

=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.

=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.

=back

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

=over

=item * RESOURCE

This is the resource's 'path'. For example, in order to GET the list of all
fields, you pass C</rest/api/latest/field>, and in order to get SLA
information about an issue you pass
C</rest/servicedeskapi/request/$key/sla>.

If you're using a method from Jira Core REST API you may omit the prefix
C</rest/api/VERSION>. For example, to GET the list of all fields you may