##master-page:HelpTemplate
##master-date:Unknown-Date
#format wiki
#language en
= Interacting with the JSS API =
It is sometimes necessary to use the JSS's RESTful API in order to automate changes to computer records. This page will help you to understand how this works, using an example.

== Background ==
The JSS at https://jss.orchard.ox.ac.uk features a full-featured RESTful API to allow programmatic interaction with the database. A good primer on how you can make use of it with Bash or Python can be found at:

 * [[https://bryson3gps.wordpress.com/2014/03/30/the-jss-rest-api-for-everyone|The JSS API for Everyone]]

You may also view the official resource documentation for the Orchard JSS at:

 * [[https://jss.orchard.ox.ac.uk/api|JSS REST API Resource Documentation]]

What follows is an example in Bash of how one might use the API to GET and PUT computer records.

== Example ==
The Department of Computer Science have two labs of 20 computers each which all run VMWare Fusion with a single key, which is changed every year as they upgrade to a new major version. The installer for VMware Fusion in the Orchard Software Centre has a postinstall_script which reads the key from the computer's record in the JSS and serialises it accordingly. One could simply go through each computer record via the web GUI and update the key each time a new major version is released, but this is quite tiresome, and so the JSS API comes to the rescue!

You will need an account with at least read permissions for the objects you wish to access in the JSS in order to use HTTP GET commands, and one with at least write permissions to use HTTP POST, and update permissions to do HTTP PUT. The Orchard model is to have two separate accounts, one for reading and one for writing, to ensure that scripts that are only supposed to read do not accidentally write data. The Orchard team will be happy to create these accounts for you on request.

N.B. For the sake of this example I will assume you are using a Mac, obviously if you wish to use a different platform you may need to modify things such as the paths to your binaries.

First we need to set some variables:

{{{#!highlight bash start=1
# Variables
JSS_URL="jss.orchard.ox.ac.uk"
API_URL="https://${JSS_URL}/JSSResource"
READ_USER="apireadonly"
READ_PASS="xxxxxxxxxxx"
WRITE_USER="apiwriteonly"
WRITE_PASS="xxxxxxxxxxx"
VMWARE_SN="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
VMWARE_VERS="9.x"
GROUP_ID="503"
SN_EA_ID="19"
SN_EA_NAME="VMware Fusion Serial Number"
#VERS_EA_ID=""
#VERS_EA_NAME=""
}}}
{{{#!highlight sh start=16
# XML blob to put
read -r -d '' XML_BLOB <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<computer>
  <extension_attributes>
    <extension_attribute>
      <id>${SN_EA_ID}</id>
      <name>${SN_EA_NAME}</name>
      <type>String</type>
      <value>${VMWARE_SN}</value>
    </extension_attribute>
  </extension_attributes>
</computer>
EOF
}}}
{{{#!highlight sh start=30
# curl_get takes one argument:
# $1: the api resource to get
curl_get() {
  /usr/bin/curl --silent \
                "${API_URL}/${1}" \
                --user "${READ_USER}:${READ_PASS}"
}
# curl_put takes two arguments:
# $1: the api resource to put
# $2: the data to put
curl_put() {
  /usr/bin/curl --silent \
                -H "Content-Type:text/xml" \
                -X PUT \
                -d "${1}" \
                "${API_URL}/${2}" \
                --user "${WRITE_USER}:${WRITE_PASS}"
}
# xmllint_cmd takes one argument:
# $1: the xml to lint
xmllint_cmd() {
  echo "${1}" | /usr/bin/xmllint --format --recover - 2> /dev/null
}
# xpath_cmd takes two arguments:
# $1: the xml to lint
# $2: the xpath expression
xpath_cmd() {
  echo "${1}" | /usr/bin/xmllint --format --recover --xpath "${2}" -
}
}}}
{{{#!highlight sh start=59
# GET the XML representation of the group
group_xml=$(curl_get "computergroups/id/${GROUP_ID}")
# Retrieve the computer ids as a string
computer_ids=$(xpath_cmd "${group_xml}" "//computers/computer/id")
}}}
{{{#!highlight sh start=63
# Parse the id numbers out of the string and attempt to PUT the data to each computer record
for i in $(echo "${computer_ids}" | sed -e 's!<id>!!g' -e 's!</id>! !g') ; do
  result=$(curl_put "${XML_BLOB}" "computers/id/${i}")
  [[ $? -eq 0 ]] || { echo "ERROR: curl returned nonzero exit code $? after attempting to PUT data with REST API."; exit 1; }
  [[ $result =~ ^\<\?'xml version'\=.+\<computer\>\<id\>[[:digit:]]+\</id\>\</computer\>$ ]] || { echo "ERROR: Unexpected response from JSS after attempting to PUT data with REST API: ${result}"; exit 1; }

  echo "SUCCESS: Computer record with id ${i} updated"
done
}}}