mapbox / node-jamf Goto Github PK

A Node.js wrapper for the Jamf Pro JSS REST API

License: Other

JavaScript 100.00%

node-jamf's Introduction

node-jamf

NOTE: This repository has been deprecated and archived. It has been mirrored to https://github.com/trevorspecht/jamf-sdk-node and will continue to live and be maintained by @trevorspecht, but will no longer have any connection to Mapbox.

A lightweight Node.js wrapper for Jamf Pro's JSS REST API.

Scope

Currently this module only supports GET requests for the JSS REST API. Support for other methods such as PUT, POST, and DELETE will be added later.

Support for the JSS Universal API may also be added later.

Installation

npm install jamf

Usage

The following code sets up the module and configures the API client with values from your local environment:

var JamfApiClient = require('jamf');

var config = {
  user: process.env.JAMF_API_USER,
  password: process.env.JAMF_API_PASSWORD,
  jamfUrl: process.env.JAMF_URL,
  format: 'json'
}

var jamf = new JamfApiClient(config);

jamf.get('/accounts', function (err, res){
  if (err) console.log(err)
  console.log(res)
});

Each Jamf API client method requires a path (e.g. /accounts) and a callback (function(err, res)) function.

For example, if you wanted to get the General and Location subsets of information about a computer with an id of 50:

jamf.get('/computers/id/50/subset/General&Location', function (err, res){
  if (err) console.log(err)
  console.log(res)
});

Examples

You can find more examples in the examples directory of this project.

Configuration

You need to configure the Jamf API client before it can make any API calls. You'll need the following for configuration:

user: username for the JSS user accessing the Jamf API
password: password for the above account
jamfUrl: the URL of your JSS instance, whether on premise or in the cloud (https://yourdomain.jamfcloud.com)
format: the format of the returned data, must be either xml (Jamf API default) or json

We recommend you create a new dedicated, least privilege API user for these scripts. The user must have the necessary privileges (create, read, update, or delete) on the JSS objects

Here's an example configuration for obtaining XML data:

var config = {
  user: 'readonlyapiuser',
  password: 'fakepassword',
  jamfUrl: 'https://fakefakefakefake.jamfcloud.com',
  format: 'xml'
}

var jamf = new JamfApiClient(config);

Tests

To run the tests for this project:

npm test

The tests use eslint for linting and tape for tests.

Feature requests and reporting bugs

Are we missing something in this module? Did you find a bug?

Please look through the list of issues (both open and closed) and see if an issue already exists for what you want to propose or report.

Don't see anything in the issues? Please create a new one!

Contributing

Contributors are welcome! If you want to contribute, please fork this repo then submit a pull request (PR).

All of your tests should pass both locally and in Travis before we'll accept your PR. We also request that you add additional test coverage and documentation updates in your PR where applicable.

Resources

You can see all available Jamf API calls by accessing /api on your JSS instance. For example, visit https://yourdomain.jamfcloud.com/api. This page also contains an API playground where you can test out requests.
The Unofficial Jamf API Docs

node-jamf's People

Contributors

Stargazers

Watchers

Forkers

rubythonode osnala ururk trevorspecht isabella232 mapclone

node-jamf's Issues

Add support for JSS Universal API

Right now this module is only a wrapper for the JSS REST API. We should update the current docs for the module to make this more clear.

Based on Jamf's blog posts, it looks like they are encouraging people to transition to the Universal API as they continue to build it out (the Universal API does not yet contain all of the same methods as the JSS REST API):

Finally, Tani Kawleit closed the session by showing off Jamf’s new Universal API. They have written the new Universal API to be modern and RESTful and expands on the existing customer API. It features token-based authentication and uses versioning while supporting pagination and sorting. Tani explained that the universal API uses only JSON for all operations and does not support XML and the payloads are lighter and contain the entire schema for easy reading.

We could potentially add support for the Universal API (https://yourdomain.jamfcloud.com/uapi/doc/) as well using the config object:

var config = {
  api: 'universal',
  token: process.env.JAMF_API_TOKEN,
  jamfUrl: process.env.JAMF_URL
}

We'd then change the base URL for this wrapper to be either this.config.jamfUrl + '/JSSResource' + path (JSS REST API) or this.config.jamfUrl + '/uapi' + path (Universal API) depending on which URL. This might introduce a breaking change as users would need to specify api: 'rest' for the JSS REST API (at the moment you don't need to do so in the config).

Also, I'm not sure if the tokens used in the JSS Universal API are long lasting (can be added to your local environment) or if they expire quickly and must be dynamically generated before making any Universal API calls. This needs to be tested and evaluated.

Add support for POST, PUT, and DELETE methods

Currently this wrapper only supports GET requests for the JSS REST API. We should add support for other HTTP methods such as POST, PUT, and DELETE.

For example, we can add a post function to the JamfApiClient object prototype and update the method for the request from GET to POST.

For these HTTP methods in particular we should add solid test fixtures for Nock as well to avoid having to test on a production API.

We should also add code samples and update the README with useful documentation for these other methods.

/cc @mapbox/security @ianshward

Should the wrapper return the full response instead of only the body?

Right now this wrapper only returns the body of the request with the following code:

  request(requestUrl, requestOptions, function(error, response, body){
    if (error) callback(error, null);
    callback(null, body);
  });

See https://github.com/mapbox/node-jamf/blob/master/lib/request.js#L24-L27 for the full context.

Should we instead return the response (via callback(null, response)) and then allow people to specify response.body? This would allow people to access other properties such as the headers and the statusCode of the response.

If we do stick with only the body, should we JSON.parse the body or keep it in its current string format so that people have to manually JSON.parse() the data?

/cc @ianshward @mapbox/security

Rename module to remove node from name

Per the npm docs on package.json files:

Don't put "js" or "node" in the name. It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)

We should remove node from node-jamf before publishing to npm. node-github renamed itself to github for similar reasons. We should also rename this repo on GitHub.

Some possible names (none exist on npm yet):

jamf
jamf-client
jamf-api