nodejs-jira-wrapper

0.0.1 • Public • Published

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

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:

Package Sidebar

Install

npm i nodejs-jira-wrapper

Weekly Downloads

0

Version

0.0.1

License

GNU

Last publish

Collaborators

  • nathan-hega