The JPS (Jamf Pro Server) API Wrapper encapsulates all available endpoints in the Classic and Pro versions of the Jamf API to make them easier and faster to use in Python.
I plan on keeping this up to date with current releases of JPS. Check the changelog for additional endpoints or changes on new JPS releases.
This project is a successor to OrganicJamf which was an API wrapper project that gained functionality as our organization needed it. As I added more and more to it I decided to rip the band-aid off and just finish out the wrapper so that it included all endpoints. This involved a rewrite to make it less time consuming to add endpoints as I plan on maintaining this for future releases of JPS. This was built as a time saving measure for automation projects dealing with JPS.
To install JPS API Wrapper run the following:
pip install jps-api-wrapper
Using with statements with the Classic and Pro modules will cause the authentication token to invalidate upon exiting. Do any requests before exiting to use the same session authentication.
from os import environ
from jps_api_wrapper.classic import Classic
from jps_api_wrapper.pro import Pro
JPS_URL = "https://example.jamfcloud.com"
USERNAME = environ["JPS_USERNAME"]
PASSWORD = environ["JPS_PASSWORD"]
with Classic(JPS_URL, USERNAME, PASSWORD) as classic:
print(classic.get_computers())
print(classic.get_computer(1001))
with Pro(JPS_URL, USERNAME, PASSWORD) as pro:
print(pro.get_mobile_devices())
If not using with statements it is recommended to invalidate the token before closing the program. You can do this manually by doing the following.
from os import environ
from jps_api_wrapper.classic import Classic
from jps_api_wrapper.pro import Pro
JPS_URL = "https://example.jamfcloud.com"
USERNAME = environ["JPS_USERNAME"]
PASSWORD = environ["JPS_PASSWORD"]
print(classic.get_building(name="Example"))
classic.session.auth.invalidate()
Any methods that require the data param will have a link to Jamf's documentation in the docstring and the method documentation for the syntax of the data that the request expects.
For some examples of jps-api-wrapper usage in real projects feel free to check out my other projects in our GitLab.
To authenticate using an API Client added with JPS 10.49 use the new client parameter when initializing a Classic or Pro method. This new parameter is set to False be default to not affect current deployments of the wrapper.
from os import environ
from jps_api_wrapper.classic import Classic
from jps_api_wrapper.pro import Pro
JPS_URL = "https://example.jamfcloud.com"
CLIENT_ID = environ["CLIENT_ID"]
CLIENT_SECRET = environ["CLIENT_SECRET"]
with Classic(JPS_URL, CLIENT_ID, CLIENT_SECRET, client=True) as classic:
print(classic.get_computers())
print(classic.get_computer(1001))
with Pro(JPS_URL, CLIENT_ID, CLIENT_SECRET, client=True) as pro:
print(pro.get_mobile_devices())
Per popular demand from my JNUC2023 session I thought I would add documentation for using keyring to authenticate. It's pretty similar to the previous authentication but instead of environment variables we'll use the keyring package to handle our secrets.
pip install keyring
Open a terminal session and enter the following command, you can replace system and username with whatever your prefer. You will be prompted to enter your chosen password.
keyring set system username
All we need to do now is retrieve the password we set in Keychain using keyring.get_password along with the parameters we chose before and then use the credentials normally to authenticate with jps-api-wrapper.
import keyring
from jps_api_wrapper.classic import Classic
from jps_api_wrapper.pro import Pro
JPS_URL = "https://example.jamfcloud.com"
USERNAME = "username"
PASSWORD = keyring.get_password("system", "username")
with Classic(JPS_URL, USERNAME, PASSWORD) as classic:
print(classic.get_computers())
print(classic.get_computer(1001))
with Pro(JPS_URL, USERNAME, PASSWORD) as pro:
print(pro.get_mobile_devices())
To have jps-api-wrapper automatically handle pagination for endpoints that support it you can use the paginate function like so. We just need to import paginate along Pro from jps_api_wrapper.Pro.
from os import environ
from jps_api_wrapper.pro import Pro, paginate
JPS_URL = "https://example.jamfcloud.com"
USERNAME = environ["JPS_USERNAME"]
PASSWORD = environ["JPS_PASSWORD"]
with Pro(JPS_URL, USERNAME, PASSWORD) as pro:
print(paginate(pro.get_mobile_devices))
To pass in any arguments or key word arguments just pass them to paginate after the endpoint method like you would pass them to the endpoint method itself. So this example of non-paginated
pro.get_mobile_devices(0, 100, sort=["id:desc"])
would instead be.
paginate(pro.get_mobile_devices, 0, 100, sort=["id:desc"])
You do not need to pass along any arguments that are not mandatory in the original method endpoint that is being passed to paginate. So this example would also work.
paginate(pro.get_mobile_devices, page_size=50)
View the ReadTheDocs
The method documentation is meant to match Jamf's API Reference for easy navigation of functionality.
- The Jamf Pro API is still under development unlike the Jamf Classic API, Jamf will typically deprecate endpoints before removing them but endpoints can be removed without warning due to security or other concerns. If you are using the Pro module please be aware of this.
- When a new version of the same endpoint is added to the Pro module it will be appended with a v* (ex Pro.get_patch_policy_dashboard_v2) until the previous version is deleted. Then the new version will retake the original name and the v2 version will be deprecated. I will try to give as much warning as possible on this but the Jamf Pro API is continuously being updated.
- data parameters come before identification in methods because it's more commonly a required field since more than one type of identification is typical (mostly in the Classic module)
- With deprecated assets like peripherals and managed preferences the get, update, and delete endpoints will be added but not creation since you shouldn't be making these anymore but you may still want to have access to disable or delete them since they're not in the GUI anymore
- Get methods that end in a plural return all values or filtered selection of all values that return in the same data format as the all request. The only exception to this is if the singular and plural word for the end of the endpoint name is the same (like software) then the all request is appended with _all to differentiate it
- The method names reflect the get, create, update, delete privilege requirements because they're more readable and easier to understand than post and put for people that aren't familiar with working with HTTP requests. Some methods are labeled to more accurately reflect the actual purpose rather than the HTTP method (i.e. Post requests that delete multiple records)
- Pro delete methods enforce type of the id and ids parameters because ids will split the list into the individual ids for processing. If this happens to a string, say "123", it will split that instead into ["1", "2", "3"] which would result in resource objects 1, 2, and 3 being deleted instead of the desired 123 resource object
- Pro methods predicated with replace are put methods that replace all existing data with the new data supplied. They are distinguished from other methods predicated by update so that someone does not mistakenly replace all data when they just meant to update
This repository contains a Pipfile for easy management of virtual environments with Pipenv. Run it, but don't create a lockfile, to install the development dependencies:
pipenv install --skip-lock --dev
To run the tests and get coverage information, run:
pipenv run pytest --cov=src --cov-report=xml --cov-report=term-missing
Files are formatted with Black prior to committing. Black is installed in your Pipenv virtual environment. Run it like this before you commit:
pipenv run black .
PRs accepted. The main repo is my organization's GitLab repo so make any pull requests there as the GitHub repo is mirrored from there.