- v3.0.2Latest
- v3.0.1
- v3.0.0
- v2.19.0
- v2.18.0
- v2.17.0
- v2.16.1
- v2.16.0
- v2.15.17
- v2.15.16
- v2.15.15
- v2.15.14
- v2.15.13
- v2.15.12
- v2.15.11
- v2.15.10
- v2.15.9
- v2.15.8
- v2.15.7
- v2.15.6
- v2.15.5
- v2.15.4
- v2.15.3
- v2.15.2
- v2.15.1
- v2.15.0
- v2.14.0
- v2.13.0
- v2.12.0
- v2.11.0
- v2.10.4
- v2.10.3
- v2.10.2
- v2.10.1
- v2.10.0
- v2.9.0
- v2.8.0
- v2.7.0
- v2.6.3
- v2.6.2
- v2.6.1
- v2.6.0
- v2.5.2
- v2.5.1
- v2.5.0
- v2.4.2
- v2.4.1
- v2.4.0
- v2.3.0
- v2.2.1
- v2.2.0
- v2.1.1
- v2.1.0
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.8.0
- v1.7.3
JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Jira API
About
jira.js is a powerful Node.JS / Browser module that allows you to interact with the Jira Cloud API, Jira Agile Cloud API, Jira ServiceDesk Cloud API very easily.
Usability, consistency, and performance are key focuses of jira.js, and it also has nearly 100% coverage of the Jira API. It receives new Jira features shortly after they arrive in the API.
Table of contents
- Installation
- Documentation
- Deprecation warnings
- Usage
- Decreasing Webpack bundle size
- Take a look at our other products
- License
Installation
Node.js 10.0.0 or newer is required.
Install with the npm:
npm install jira.jsInstall with the yarn:
yarn add jira.jsDocumentation
You can find the documentation here.
Deprecation warnings
- Deprecation warning: New error handling mechanism added. Please use
newErrorHandling: truein configWe are using a new error handling mechanism (instead throwing raw axios error will be showed API response). For enable it, make following changes in your config:
const client = new Version3Client({ host: '...', newErrorHandling: true, // This flag enable new error handling. }); // Examples /** Old error handling **/ const client = new Version3Client({ host: '...' }); client.issues.createIssue(); // Output: // { // code: 'ERR_BAD_REQUEST', // config: { a lot of stuff here }, // request: { a lot of stuff here }, // response: { // a lot of stuff here
// data: { // errorMessages: [], // errors: { project: ‘Specify a valid project ID or key’ } // }, // a lot of stuff here // }, // a lot of stuff here // }
/** New error handling **/
const client = new Version3Client({ host: ‘…’, newErrorHandling: true });
client.issues.createIssue();
// Output: // { // errorMessages: [], // errors: { project: ‘Specify a valid project ID or key’ } // } “`
Usage
Authentication
There are several types of authentication to gain access to the Jira API. Let’s take a look at a few of them below
Basic authentication
Basic authentication allows you to log in with credentials. You can use username and password, but this login method is not supported in the online version and most standalone versions, so it’s better to release API Token, read how to do it here, and use it together with email.
Username and password example:
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
basic: {
username: 'YOUR_USERNAME',
password: 'YOUR_PASSWORD',
},
},
});Email and API Token example:
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
basic: {
email: 'YOUR@EMAIL.ORG',
apiToken: 'YOUR_API_TOKEN',
},
},
});OAuth
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
oauth: {
consumerKey: 'your consumer key',
consumerSecret: '-----BEGIN RSA PRIVATE KEY-----\n" + "some private key\n" + "-----END RSA PRIVATE KEY-----',
accessToken: 'your access token',
tokenSecret: 'your token secret',
},
},
});OAuth 2.0
Only the authorization token is currently supported. To release it, you need to read the documentation and write your own code to get the token.
Example of usage
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
oauth2: {
accessToken: 'YOUR_ACCESS_TOKEN',
},
},
});JWT
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
jwt: {
issuer: 'ISSUER',
secret: 'shhhh',
expiryTimeSeconds: 180,
},
},
});Personal access token
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
personalAccessToken: 'secrectPAT',
},
});Your first request and using algorithm
import { Version2Client } from 'jira.js';
const client = new Version2Client({
host: 'https://your-domain.atlassian.net',
authentication: {
basic: {
email: 'YOUR_EMAIL',
apiToken: 'YOUR_API_TOKEN',
},
},
});
async function main() {
const projects = await client.projects.getAllProjects();
console.log(projects);
}
main();
// Expected output:
// [
// {
// expand: 'description,lead,issueTypes,url,projectKeys,permissions,insight',
// self: 'https://your-domain.atlassian.net/rest/api/2/project/10000',
// id: '10000',
// key: 'TEST',
// name: 'test',
// avatarUrls: {
// '48x48': 'https://your-domain.atlassian.net/secure/projectavatar?pid=10000&avatarId=10425',
// '24x24': 'https://your-domain.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10425',
// '16x16': 'https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10425',
// '32x32': 'https://your-domain.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10425'
// },
// projectTypeKey: 'software',
// simplified: true,
// style: 'next-gen',
// isPrivate: false,
// properties: {},
// entityId: 'e0a412bd-1510-4841-bdbc-84180db3ee3b',
// uuid: 'e0a412bd-1510-4841-bdbc-84180db3ee3b'
// }
// ]The algorithm for using the library:
client.<group>.<methodName>(parametersObject);Available groups:
Agile Cloud API group
Version 2 Cloud REST API group
Version 3 Cloud REST API group
Service Desk Cloud API group
The name of the methods is the name of the endpoint in the group without spaces and in camelCase.
The parameters depend on the specific endpoint. For more information, see here.
Decreasing Webpack bundle size
If you use Webpack and need to reduce the size of the assembly, you can create your client with only the groups you use.
import { BaseClient } from 'jira.js';
import { Board } from 'jira.js/out/agile';
import { Groups } from 'jira.js/out/version2';
import { Issues } from 'jira.js/out/version3';
export class CustomJiraClient extends BaseClient {
board = new Board(this);
groups = new Groups(this);
issues = new Issues(this);
}Take a look at our other products
- Confluence.js - confluence.js is a powerful Node.JS / Browser module that allows you to interact with the Confluence API very easily
- Trello.js - JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Trello API
License
Distributed under the MIT License. See LICENSE for more information.