Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
node module to work with redmine api rewrited to be promises/A+ compliant
JavaScript
Branch: master

README.md

node-promised-redmine

Redmine REST API Client for node.js implemented with promises/A+ Codacy Badge Build Status

This was a modified version of the original redmine module by sotarok using D.js to implement it as a promises/A+ compatible api. But it has been largely rewrote since and is a totally different project now.

Features

  • support both http / https protocols
  • support basicAuth authentication
  • compatible with promises/A+ through D.js
  • simple api
  • recursively retrieve issues until given date
  • exponential backoff retries

Main methods

  • Settings getter/setter

    • all setters return the Redmine instance and are chainable
    • (get|set)ApiKey(key) api key given by your redmine server
    • (get|set)Host(host) ip or hostname of the redmine api endpoint
    • (get|set)Port(port) set remote server port default to 80
    • (get|set)BasicAuth(auth) string used as auth option of the http request
    • (get|set)Protocol(protocol) http or https
    • (get|set)PathPrefix(prefix) path prefix to prepend to each request paths
    • (get|set)SslCaCert(certFilePath) path or array of path to authority certificates files to check the remote host against
    • (get|set)SslClientCert(certFilePath) path to public x509 certificate file to use
    • setSslClientKey(keyFilePath, passPhrase)* path to client private key file to use for SSL and associated passphrase
    • (get|set)MaxTry(maxTry) max number of retry on request error default to 1 (get|set)MaxDelay(maxDelay) max time in ms to wait between two retry on request error default to 2000 (get|set)Verbose(verbose) boolean value that turn on/off console.log on errors and retries. (default setting to false)
  • Generics

    • all generic methods path doesn't require leading slash nor the .json extension e.g. for issues it can be "issues" or "issues/{id}"
    • get(path, params) get a single resource or a list or resources
    • getAllSince(what, since, params) helper to get all items of a collection since the given date (isoString or Date instance)
    • post(path, params) create a new resource on corresponding path
    • put(path, params) update a given resource with params
    • del(path, params) remove given resource
  • Issues

    • getIssues(params) return list of issues (max 100)
    • getIssue(id, params) return an issue details by its id
    • getAllIssuesSince(since, params) return all issues since given date (isoString or Date instance)
    • postIssue(issue, params) create a new issue
    • updateIssue(id, issue, params) update issue with given id
    • deleteIssue(id, params) delete an issue by its id
  • Users
    • getUsers(params) return list of users (max 100)
    • getUser(id, params) retrieve user details by its id
    • getUserCurrent(params) return current user (the one corresponding to the apiKey)
  • Projects
    • getProjects(params) get a list of projects (max 100)
    • getProject(id, params) return details about a single project by its id
    • getAllProjectsSince(since, params) return all projects updated since given date (isoString or Date instance)
  • Time Entries
    • getTimeEntries(params) returns a list of time entries
    • getTimeEntry(id, params) returns time entry of given id
    • postTimeEntry(timeEntry, params) returns time entry of given id
    • updateTimeEntry(id, timeEntry, params) update time entry corresponding to the given id
    • deleteTimeEntry(id, params) delete time entry of given id

Generic Parameters

All request made can use following additional parameters in the params argument:

  • retry: a retry settings based on an exponential backoff algorithm. You can set thoose settings for all request using setMaxRetry and setMaxDelay methods, or on a request basis by passing a retry property to the params parameter. This retry property should be an object with one or two property of maxTry and maxDelay e.g. var params = {retry: {maxTry:3}}
  • impersonate: allow you to add a X-Redmine-Switch-User header on a request basis. This will only work when you are authenticated as an admin user in the first place. var params = {impersonate: 'username'};

Basic Usage example

var Redmine = require('promised-redmine');
var config = {
  host: "localhost", // required
  apiKey: "XXXXXX", // required
  pathPrefix: "/myRedminePath",
  protocol: "http",
  // if using SSL settings, change protocol and port accordingly
  sslCaCert: '/path/to/root/ca.pem', // defaults to null
  sslClientCert: '/path/to/client/cert.pem', // defaults to null
  sslClientKey: '/path/to/client/cert.key', // defaults to null
  sslClientPassphrase: 'clientKeyPassphrase' // defaults to null
}
var redmineApi = new Redmine(config);
redmineApi.getIssues()
  .success(function(issues){ // success is an alias of then without the promise rejection management in D.js the underlying promise library
    // do something with that
  })

Install

Install from npm:

$ npm install promised-redmine

Link

How to help

Contributions are always welcome. I have no more redmine installation available for testing. So if you have one you can share for testing purpose, it will be of great help to this project.

Something went wrong with that request. Please try again.