Proposed changes to the API docs

API.md

Sal has a REST API. You will need to create an API key before using it. You should send your private key and public key as headers (publickey and privatekey). Some actions can only be performed by API keys that have been marked as read / write in Sal.

General notes

Sal's API will generally return a response similar to the following:

{"count":362,"next":"https://sal.example.com/api/conditions/?condition=machine_type&page=2","previous":null,"results":[...]}

Where count is the number of records the API is able to return, next is the URL you need to query to get the next batch, previous is the previous batch, and results is the actual data you have requested. The format of this will change depending on which API endpoint you call.

Machines

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/machines/

Will retrieve all machines.

To retrieve a single machine:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/machines/MACHINESERIALNUMBER/

To create a machine, you will need to send a JSON object as the POST data. You can use any key that can be retrieved from the API except:

• Facts
• Conditions
• Pending Apple Updates
• Pending 3rd Party Updates

You must set machine_group to the ID of the Machine Group the computer is to be placed into.

You can delete a machine by sending a DELETE command with your request (please see this guide on using REST APIs if that doesn't make sense!)

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" -X DELETE http://sal/api/machines/MACHINESERIALNUMBER/

Facts

You can retrieve all facts for a machine:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/facts/MACHINESERIALNUMBER/

To retrieve all machines with a particular fact:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/facts/?fact=FACTNAME

Munki Conditions

To retrieve all Munki Conditions for a machine:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/conditions/MACHINESERIALNUMBER/

To retrieve all machines with a particular condition:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/conditions/?condition=CONDITIONNAME

Machine Groups

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/machine_groups/

Will retrieve all machine groups.

To retrieve a single machine group:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/machine_groups/MACHINEGROUPID/

To create a Machine Group, you will need to send a JSON object as the POST data. You can use any key that can be retrieved from the API.

You must set business_unit to the ID of the Business Unit the Machine Group is to be placed into.

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" --data '{"name":"CarneAsada","business_unit":12}' http://sal/api/machine_groups/

You can delete a machine group by sending a DELETE command with your request to the desired Machine Group's ID.

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" -X DELETE http://sal/api/machine_groups/42/

Business Units

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/business_units/

Will retrieve all Business Units.

To retrieve a single Business Unit:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/business_units/BUSINESSUNITID/

To create a Business Unit, you will need to send a JSON object as the POST data.

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" --data '{"name":"TacoConsumptionDivision"}' http://sal/api/business_units/

You can use any key that can be retrieved from the API.

You can delete a Business Unit by sending a DELETE command with your request. Specify the ID of the Business Unit to delete in the URL.

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" -X DELETE http://sal/api/business_units/12/

External scripts

To retrieve all external script entries:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/plugin_script_submissions/

To retrieve one for a particular machine:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/plugin_script_submissions/SERIALNUMBER/

To retrieve the rows for a certain machine:

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/plugin_script_rows/SERIALNUMBER/

Search

To perform a basic search via the API (same as using the search field):

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/search/?query=YOURQUERYHERE

To run a saved search (constructed in the GUI):

$ curl -H "privatekey:YOURPRIVATEKEY" -H "publickey:YOURPUBLICKEY" http://sal/api/search/SEARCHID

Where SEARCHID is the unique ID of the search.

Python

All of the examples above can easily be done in python using the requests library. Visit their site for instructions on installation.

Lets use an example of getting the amount of RAM for a particular machine.

import requests
import json

headers = {'privatekey': 'YOURPRIVATEKEY', 'publickey': 'YOURPUBLICKEY'}

r = requests.get('http://sal/api/machines/MACHINESERIALNUMBER/', headers=headers)

machine_info = r.json()

machine_memory = machine_info['results']['memory']

print(machine_memory)

If all goes well you should see an output of something like below.

16 GB