JIRA-REST

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

0.024     2024-01-21 14:05:30-03:00 America/Sao_Paulo

  [Enhancement]

  - JIRA::REST gives up on trying to decode the error messages returned by
    Jira. They are inconsistent and undocumented, as far as I know. From now on,
    we simply show the JSON object containing the error message.

  - Don't croak anymore on the PUT and POST methods when the third argument
    (value) is undefined. There are API endpoints for which this makes sense.

0.023     2022-04-10 20:54:14-03:00 America/Sao_Paulo

  [New features]

  - Implement the new JIRA::REST::rest_client auxiliary method to make it
    OK to get to the underlying REST::Client object.

  [Documentation]

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

    }

    return $iter->{results}{issues}[$iter->{offset}++ - $iter->{results}{startAt}];
}

sub attach_files {
    my ($self, $issueIdOrKey, @files) = @_;

    # We need to violate the REST::Client class encapsulation to implement
    # the HTTP POST method necessary to invoke the /issue/key/attachments
    # REST endpoint because it has to use the form-data Content-Type.

    my $rest = $self->{rest};

    # FIXME: How to attach all files at once?
    foreach my $file (@files) {
        my $response = $rest->getUseragent()->post(
            $rest->getHost . "/rest/api/latest/issue/$issueIdOrKey/attachments",
            %{$rest->{_headers}},
            'X-Atlassian-Token' => 'nocheck',
            'Content-Type'      => 'form-data',

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

This module implements a very thin wrapper around Jira's REST APIs:

=over

=item * L<Jira Core REST API|https://docs.atlassian.com/software/jira/docs/api/REST/latest/>

This rich API superseded the old L<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 C</rest/api/VERSION>.

=item * L<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 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

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

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'
    });

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

same options, adding to them the B<session> option. New code should use the
default constructor with the B<session> option because this constructor may be
deprecated in the future.

=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

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

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:

=over

=item * application/json

The majority of the API's resources return JSON values. Those are
decoded using the C<decode> method of a C<JSON> object. Most of the
endpoints return hashes, which are returned as a Perl hash reference.

=item * text/plain

Those values are returned as simple strings.

=back

Some endpoints don't return anything. In those cases, the methods
return C<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>

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

Returns the L<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.

=head2 B<set_search_iterator> PARAMS

Sets up an iterator for the search specified by the hash reference PARAMS.
It must be called before calls to B<next_issue>.

PARAMS must conform with the query parameters allowed for the
C</rest/api/2/search> Jira REST endpoint.

=head2 B<next_issue>

This must be called after a call to B<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.

=head2 B<attach_files> ISSUE FILE...

The C</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 C<REST::Client> interface. This utility method offers an easier
interface to attach files to issues.

=head1 PERL AND JIRA COMPATIBILITY POLICY

Currently L<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 L<Ubuntu