#Node.js JIRA API Wrapper
This module was meant to wrap and simplify the JIRA API. The wrapper currently supports only a small fraction of the API calls available. A large number of the API calls are meant only to specify the data being returned. Not supporting some of these calls was intentional as it is an over complication. Read below for:
Usage
NOTE: Code was developed against version 2 of the JIRA API. Eg: /rest/api/2/
Users can provide a username and password or a base64 encoded authentication string.
Initialization
// authenticate with username:password
jira = require('nodejs-jira-wrapper')({
username: 'username',
password: 'alligator1',
url: 'https://jira.api.com/rest/api/2/'
});
// or with encoded string
jira = require('nodejs-jira-wrapper')({
authorization: 'XBFUH8kKJBJdjb89KJNJnj9',
url: 'https://jira.api.com/rest/api/2/'
});
Use callbacks to asynchronously communicate with the JIRA API.
Example Usage
var _ = require('lodash');
var jira = require('nodejs-jira-wrapper')({
username: 'username',
password: 'alligator1',
url: 'https://jira.api.com/rest/api/2/'
});
// get all JIRA project keys
jira.projects.get(null, function (error, body) {
if (error) {
// throw some error
throw new 'jira api wrapper failed'
} else {
var keys = [];
_.each(body, function (project) {
keys.push(project.key);
});
}
});
NOTE: Errors are always returned as:
{ 'statusCode': 401, // some digit 'message': 'Unauthorized' // some error string }
Supported Calls
Projects
GET
jira.projects.get
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e3818
Retrieve information about a project(s).
Parameter | Description |
---|---|
options | This value can be null or an object
|
callback | Function that accepts an error and a body object |
// options object needs an id key that is either a string
var options = {
id: 'JIRAKEY'
}
jira.projects.get(options, function (error, body) {
// ...
}
// or an arry
var options = {
id: ['JIRAKEY1', 'JIRAKEY2']
}
jira.projects.get(options, function (error, body) {
// ...
}
// null returns all projects
jira.projects.get(null, function (error, body) {
// ...
}
Issues
GET
jira.issues.get
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e296
Retrieve information about an issue.
Parameter | Description |
---|---|
options | This value must be an object with the key id specified |
callback | Function that accepts an error and a body object |
POST
jira.issues.post
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e86
Create a new issue.
Parameter | Description |
---|---|
options | Must be object representing a JIRA issue - example below
|
callback | Function that accepts an error and a body object |
// set up the jira object
var options = {
"fields": {
"project": {
"id": "17412"
},
"summary": "api test issue.",
"description": "Creating of an issue using ids for projects and issue types using the REST API",
"issuetype": {
"id": "19"
}
}
};
jira.issues.post(options, function (error, data) {
// ...
})
DELETE
jira.issues.delete
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e296
Remove an issue.
Parameter | Description |
---|---|
options | This value must be an object with the key id specified |
callback | Function that accepts an error and a body object |
PUT
jira.issues.put
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e296
Edit/Update an issue.
Parameter | Description |
---|---|
options | This value must be an object with the key id specified |
callback | Function that accepts an error and a body object |
EDITMETA
jira.issues.editmeta
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e586
Retrieve information about what fields you can edit for a particular issue. Use this in conjunction with the PUT
call.
Parameter | Description |
---|---|
options | This value must be an object with the key id specified |
callback | Function that accepts an error and a body object |
CREATEMETA
jira.issues.createmeta
https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e550
Retrieve information about what fields you need to supply in order to create an issue. Use this is conjunction with the POST
call.
Parameter | Description |
---|---|
options | Options will represent the query string to send with the createmeta call. See JIRA documentation for appropriate key names and values |
callback | Function that accepts an error and a body object |
var options = {
projectIds: 11111,
projectKeys: 'TESTJS',
//issuetypeIds: ['16', '17'],
//issuetypeNames: ['Milestone Marker', 'Prelaunch Subtask']
};
jira.issues.createmeta(options, function (error, data) {
// ...
});
Development
The JIRA API has a lot of functionality. While I don't think this module needs to wrap every single API endpoint, I think it is lacking some crucial functionality. See the TODO section for more details.
Issues
Bugs When submitting a github issue for a bug, please be sure to provide the following:
- Explanation of the bug and any context
- Steps to reproduce
- Expected result
- Actual result
New Features When submitting an issue for a new feature request, please be sure to provide the folllowing:
- Explanation of the new feature and any context
- If applicable, link to the JIRA API call (https://docs.atlassian.com/software/jira/docs/api/REST/latest/)
PRs
Thank you for helping!
When submitting a PR, the following will be required:
- Adhere to the styles of the file you are working in
- Provide a clear description and testing instructions
- Update to the README.md file documenting your changes
- Test function written in
lib/tests.js
Testing
There is a decent, but sparse, testing suite written for development. It supports running through the entire suite of test (for making global changes) or executing a specific set of tests. Below are some examples of using the test suite:
# specify tests with a comma separated string
node lib/test.js --s "getprojects, createmeta" --un username --pw password! --url "https://jira.api.com/rest/api/2/"
# specify tests as a single string
node lib/test.js --s "getprojects" --un username --pw password! --url "https://jira.api.com/rest/api/2/"
# let the full suite run
node lib/test.js --un username --pw password! --url "https://jira.api.com/rest/api/2/"
Example Output:
» node lib/test.js --s "getprojects, createmeta" --un username --pw password --url "https://jira.api.com/rest/api/2/"
name: getprojects
success: false
reference: https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e4611
description: validates the wrapper around the project GET call is functioning properly
result: {"error":{"statusCode":401,"message":"Unauthorized"},"body":null}
----------------------------------------------------------
name: createmeta
success: false
reference: https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e550
description: validates the wrapper around the issue createmeta call is functioning properly
result: {"error":{"statusCode":401,"message":"Unauthorized"},"body":null}
----------------------------------------------------------
»
TODO
In order of importance.
Testing
Only two of the seven wrapper functions have tests written. Adding the rest of the tests is important because it helps enforce all new functionality requiring a test and it provides confidence while developing and reviewing pull requests.
On top of writing the rest of the tests, support has to be added for a developer defined test configuration. This would remove the need for query parameters and allow for writing more complex tests (removing an issue, creating an issue, etc...).
New Functionality
As I mentioned above, there are plenty of API calls that should be wrapped. Below is my best-guess at what functionality developers would want:
- Bulk Creating Issues
- This might already be supported by my
jira.issues.post
call, I just haven't explicitly tested for it. - https://docs.atlassian.com/software/jira/docs/api/REST/latest/#d2e516
- This might already be supported by my
- Search functionality
- Users/Workflows/Schemes
- Administration/Configuration functionality