JIRA::REST(3pm)

📦
version 0.025 · 4 versions
, in ubuntu stonking

✨ NAME ✨

JIRA::REST — a thin wrapper around Jira's REST API 🦋

okay so this is JIRA::REST(3pm), which lives in the User Contributed Perl Documentation part of your man pages, and bestie it is exactly what it says on the tin: a lil' baby layer of Perl sugar sitting on top of Jira's REST endpoints so you don't have to hand-roll HTTP calls like it's 2009. 💅

🎀 VERSION 🎀

version 0.025

🌸 SYNOPSIS 🌸

the vibe is: make an object, hit some endpoints, live your truth ✨

use JIRA::REST;

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

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

my $jira_with_pat = JIRA::REST->new({
    url => 'https://jira.example.net',
    pat => 'NDc4NDkyNDg3ODE3OstHYSeYC1GnuqRacSqvUbookcZk',
});

my $jira_anonymous = JIRA::REST->new({
    url => 'https://jira.example.net',
    anonymous => 1,
});

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

like. it's giving so much convenience. 😌

💫 DESCRIPTION 💫

Jira is a proprietary bug tracking system from Atlassian, and you can find it over at http://www.atlassian.com/software/jira/. 🐞

This module implements a very thin wrapper around Jira's REST APIs, and here's the lineup:

This rich API superseded the old Jira SOAP API, which lives at http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html — and that one isn't supported anymore as of Jira version 7, so like, do not go there. 💀

The endpoints of this API have a path prefix of /rest/api/VERSION.

This API deals with the objects of the Jira Service Desk application. Its endpoints have a path prefix of /rest/servicedeskapi.

This API deals with the objects of the Jira Software application. Its endpoints have a path prefix of /rest/agile/VERSION.

🛠️ CONSTRUCTORS 🛠️

new HASHREF

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 actually need. The second form forces you to pass undefined values if you need to reach a specific argument further to the right. 🙈 like, so many undefs. no thank you.

The arguments are described below with the names which must be used as the hash keys:

  • 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 (/rest/api/VERSION, /rest/servicedeskapi, or /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. 💅 set it once, forget it forever.

  • anonymous — the boolean 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. 👀
  • pat — the pat authentication argument is a string representing a 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. 🎟️
  • client_id
  • client_secret
  • scope

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

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

  • username
  • password

The username and 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 username or password isn't defined the module looks them up in either the .netrc file or via Config::Identity (which allows gpg encrypted credentials). 🔐

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

  • session — the boolean session argument tells the module if you want it to acquire a session cookie by making a 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 DELETE /rest/auth/1/session call to logout from Jira. 🍪

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

  • rest_client_config — a JIRA::REST object uses a 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 url argument overwrites any value associated with the host key in this hash. 😤 rude but true.
  • 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. 🌐
  • ssl_verify_none — sets the SSL_verify_mode and verify_hostname ssl 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. 🫣
bestie, that last one is literally turning off certificate verification. it exists for self-signed-cert servers, and that's the whole reason. don't go flipping it on for funsies. 💀

✨ REST METHODS ✨

okay bestie, so Jira's REST API documentation lists dozens of "resources" which can be operated via the standard HTTP requests: GET, DELETE, PUT, and POST. And 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. slay 💅

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

🌟 GET RESOURCE [, QUERY] 🌟

Returns the RESOURCE as a Perl data structure.

🗑️ DELETE RESOURCE [, QUERY] 🗑️

Deletes the RESOURCE.

✨ PUT RESOURCE, QUERY, VALUE [, HEADERS] ✨

Creates RESOURCE based on VALUE.

📝 POST RESOURCE, QUERY, VALUE [, HEADERS] 📝

Updates RESOURCE based on VALUE.

🛠️ UTILITY METHODS 🛠️

This module provides a few utility methods. lowkey helpful fr fr

🔌 rest_client

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

🔍 set_search_iterator PARAMS

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

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

➡️ next_issue

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

📎 attach_files ISSUE FILE...

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

🌈 PERL AND JIRA COMPATIBILITY POLICY 🌈

Currently JIRA::REST requires Perl 5.34 and is tested on Jira Data Center 11.3.7. 💅

We try to be compatible with the Perl native packages of the oldest Ubuntu LTS https://www.ubuntu.com/info/release-end-of-life Linux distribution still getting maintenance updates. 🐧

+-------------+-------------------------+------+
| End of Life | Distro                  | Perl |
+-------------+-------------------------+------+
|   2027-04   | Ubuntu 22.04 (jammy)    | 5.34 |
|   2029-04   | Ubuntu 24.04 (noble)    | 5.38 |
|   2031-04   | Ubuntu 26.04 (resolute) | 5.40 |
+-------------+-------------------------+------+

As for Jira, the policy is very lax. I (the author) only test JIRA::REST on the Jira Data Center 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::REST::OAuth" — This module Sub Classes JIRA::REST providing OAuth 1.0 support. 🔐
  • "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 📦

https://github.com/gnustavo/JIRA-REST

✍️ AUTHOR ✍️

Gustavo L. de M. Chaves <gnustavo@cpan.org>

This software is copyright (c) 2026 by CPQD <www.cpqd.com.br>.

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

and that's the vibe check ✅ this page is JIRA::REST(3pm), made with perl v5.40.1, dated 2026-07-05. bye bestie! 💖🦋

📦 where this page comes from