NAME¶

VERSION¶

SYNOPSIS¶

    use JIRA::REST;

    my $jira = JIRA::REST->new({
        URL      => 'https://jira.example.net',
        username => 'myuser',
        password => 'mypass',
    });

    # 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¶

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

• Jira Core REST API <https://docs.atlassian.com/jira/REST/server/>

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

CONSTRUCTOR¶

REST METHODS¶

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 form 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".

UTILITY METHODS¶

PERL AND JIRA COMPATIBILITY POLICY¶

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.

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

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::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¶

AUTHOR¶

COPYRIGHT AND LICENSE¶

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.