API - examples

Below is a list of examples on development of interfaces or other machine to machine communication. The documentation is interactive, and is made available after authentication on FQDN+/istools/api/documentation The authentication is made on FQDN (for instance swe05.istools.com)+/istools/api

Examples are using BASH, CURL and JQ. The data format JSON is used.

Please take care when copying/pasting not to include unintended row breaks.

Writing a value to a dropdown The below example uses the following endpoints:
  • get /api/apps/{appid}/tables
  • get /api/apps/{appid}/fields
  • get /api/apps/{appid}/fieldgroups/{fieldId}
  • put /api/apps/{appid}/tables/{tableId}/records/{recordId}

They are used in the following workflow:

Workflow
BASH, CURL and JQ

  1. Start by fetching the table with the list

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:application/json" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/tables") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; jq '.' < "${_tempfile}"
rm "${_tempfile}"

  2. Then get the fields of the table using the id from the first query

    _tableid=<table id from above, returned as value>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:application/json" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/fields/?links=true&table=${_tableid}") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; jq '.' < "${_tempfile}"
rm "${_tempfile}"

  3. Save the field id, and then use the extra information to fetch the valid dropdown values

    _listid=<list id from above, returned as extra.target.value>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:application/json" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/fieldgroups/${_listid}") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; jq '.' < "${_tempfile}"
rm "${_tempfile}"

  4. To save a value, use the dropdown properties from above with the field id

    _fieldid=<field id from second step above, returned as value>
_listitemuri=<list item uri, from above returned in members as uri>
_listitemvalue=<list item value, from above returned in members as value>
_recorduri=<record uri of record to update> # fetch using get /api/apps/{appid}/tables/{tableId}/records
_tempfile=$(mktemp)
_recorddata="{ \"uri\" : \"${_recorduri}\", \"fieldData\" : { \"${_fieldid}\" : {\"uri\" : \"${_listitemuri}\", \"value\" : ${_listitemvalue} } } }" 
_httpstatus=$(curl -s -H "Content-Type:application/json" -H "Accept:*/*" -o "${_tempfile}" -w "%{http_code}" -X PUT -u "${_aname}:${_akey}" -d "${_recorddata}" "${_baseurl}/${_recorduri#/}") # -s for silent, -H to specify content type and accept all replies, -o to specify output file, -w to write-out variable http code, -X PUT to use put request, -d to inlude data
echo "http status code: ${_httpstatus}"
echo "response:"; cat "${_tempfile}"
rm "${_tempfile}"
Queing a report template, and fetching the report

The below example is based on a role-based report, and uses the following endpoints:

  • get /api/apps/{appid}/reports/rolebased
  • post /api/apps/{appid}/reports/queue/{reportId}
  • get /api/apps/{appid}/reports/queue/{qid}/status
  • get /api/apps/{appid}/reports/queue/{qid}

They are used in the following workflow:

Workflow

A role-based report has a set of characteristics, and in this case noting a specific report may not be queued more than once within a set timeframe (usually 4h).

BASH, CURL and JQ

  1. Start by fetching the list of role-based reports:

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:application/json" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/reports/rolebased") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; jq '.' < "${_tempfile}"
rm "${_tempfile}"

  2. Use the template id from above, and queue the template

    _templateid=<template id, from above returned as reportId>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Content-Type:application/json" -H "Accept:*/*" -o "${_tempfile}" -w "%{http_code}" -X POST -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/reports/queue/${_templateid}?format=xlsx&zipped=false") # -s for silent, -H to specify JSON data, -H to specify return format, -o to specify output file, -w to write-out variable http code, -X POST to use post request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response (queue id if successful):"; cat "${_tempfile}"
rm "${_tempfile}"

  3. Investigate status of report using queue id from above

    _queueid=<queue id, from above>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:*/*" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/reports/queue/${_queueid}/status") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; cat "${_tempfile}"
rm "${_tempfile}"

  4. After status "FINISHED", fetch the report

    _queueid=<queue id, from above>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Accept:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -o "${_tempfile}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/reports/queue/${_queueid}?dispositionType=attachment&delete=false") # -s for silent, -H to force JSON response, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
_reportfile="${_tempfile##*/}"
_reportfile="${_reportfile/./}.xlsx"
cp "${_tempfile}" "./${_reportfile}"
echo "report file: ${_reportfile}"
rm "${_tempfile}"
Uploading and downloading files

The below example uses the following endpoints:

  • post /api/apps/{appid}/tables/{tableid}/records/{recordid}/fielddata/{fieldid}
  • get /api/apps/{appid}/tables/{tableid}/records/{recordid}/fielddata/{fieldid}

They are used in the following workflow:

Workflow
BASH, CURL and JQ

  1. Uploading a file:

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_tableid=<Table ID>
_fieldid=<Field ID>
_recordid=<Record ID>
_filepath=<File to upload>
_tempfile=$(mktemp)
_httpstatus=$(curl -s -H "Content-Type: multipart/form-data" -F "file=@${_filepath}" -o "${_tempfile}" -w "%{http_code}" -X POST -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/tables/${_tableid}/records/${_recordid}/fielddata/${_fieldid}") # -s for silent, -H to declare multipart, -o to specify output file, -w to write-out variable http code, -X POST to use post request, -u for credentials
echo "http status code: ${_httpstatus}"
echo "response:"; jq '.' < "${_tempfile}"
rm "${_tempfile}"

  2. Downloading a file:

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_tableid=<Table ID>
_fieldid=<Field ID>
_recordid=<Record ID>
_filepath=<Path of downloaded file>
_httpstatus=$(curl -s -H "Accept: */*" -o "${_filepath}" -w "%{http_code}" -X GET -u "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/tables/${_tableid}/records/${_recordid}/fielddata/${_fieldid}") # -s for silent, -H accept all types, -o to specify output file, -w to write-out variable http code, -X GET to use get request, -u for credentials
echo "http status code: ${_httpstatus}"
Subscribing to changes, push implementation

This is a simple example demonstrating how changes from three fields within one table are written to another table in the same application as a log of changes.

The below example uses the following endpoints:

  • post /api/apps/{appid}/datalog/channels
  • get /api/apps/{appid}/datalog/channels/{channel}/
  • post /api/apps/{appid}/tables/{tableid}/records

They are used in the following workflow:

Workflow
BASH, CURL och JQ

  1. Create a channel to subscribe to:

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_channelDefinition='{ "tables": [ <table id> ], "fields": [ <field id 1>, <field id 2>, <field id 3> ] }'
_tempfile=$(mktemp)
_httpstatus=$(curl --silent --header "Content-Type: application/json" --output "${_tempfile}" --write-out "%{http_code}" --request POST --user "${_aname}:${_akey}" "${_baseurl}/apps/${_appid}/datalog/channels") 
echo "http status code: ${_httpstatus}"
echo "response:"$(jq '.' < "${_tempfile}")
rm "${_tempfile}"

  2. Use the ID of the newly created channel from above, and start subscribing to the channel. This call is used until a response is given, which is when something changed. Thereafter the offset, the parameter since, must be incremented by 1 before the next call. If the parameter timeout is not used the return status of the client must be monitored (timeout).

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_channelid=<the created channel ID>
_offset=0 # starts at 0, increments by 1
_timeout=30000 # milliseconds
_tempfile=$(mktemp)
_httpstatus=$(curl --silent --header "Content-Type: application/json" --output "${_tempfile}" --write-out "%{http_code}" --user "${_aname}:${_akey}" -G --data-urlencode "since=${_offset}" --data-urlencode "timeout=${_timeout}" "${_baseurl}/apps/${_appid}/datalog/channels/${_channelid}") 
_curlexitcode="$?"
echo "curl exit code: ${_curlexitcode}"
echo "http status code: ${_httpstatus}"
echo "response:"$(jq '.' < "${_tempfile}")
rm "${_tempfile}"

  3. The response from above includes changed records and fields, which are written to another table:

    _baseurl=https://<environment name>.istools.com/istools/api # the IS Tools environment API base URL
_aname=<service account name>
_akey=<service account key>
_appid=<IS Tools application ID>
_tableid=<table ID for storing changes>
_json='{
  "title": "<record name>",
  "fieldData": {
    "<field id 1>": { "uri": "<field 1 uri>", "value": "<field 1 value>" },
    "<field id 2>": { "uri": "<field 2 uri>", "value": "<field 2 value>" },
    "<field id 3>": { "uri": "<field 3 uri>", "value": "<field 3 value>" }
  }
}'
_tempfile=$(mktemp)
_httpstatus=$(curl --silent --header "Content-Type: application/json" --output "${_tempfile}" --write-out "%{http_code}" --user "${_aname}:${_akey}" --request POST --data "${_json}" "${_baseurl}/apps/${_appid}/tables/${_tableid}/records") 
_curlexitcode="$?"
echo "curl exit code: ${_curlexitcode}"
echo "http status code: ${_httpstatus}"
echo "response:"$(jq '.' < "${_tempfile}")
rm "${_tempfile}"

More tips