API - common questions

API - common questions

Below is a list of answers to common questions 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

They are listed with examples 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}

    BASH, CURL och JQ

    1. Start by fetching the table with the list
      _baseurl=https://.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:"; cat "${_tempfile}" | jq '.'
      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:"; cat "${_tempfile}" | jq '.'
      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:"; cat "${_tempfile}" | jq '.'
      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}

    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 och JQ

    1. Start by fetching the list of role-based reports:
      _baseurl=https://.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:"; cat "${_tempfile}" | jq '.'
      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}"

News

Developing a solution that reduces the need for consultants, while being a consultant, may seem like a stupid choice. However, that's exactly the road Johan Barrebo, founder and CEO at IS Tools, chose to take.
– We've now managed to establish ourselves in Europe and I see great opportunities to claim market shares also in other countries, he says.

Increased growth meant additional processes and more information that had to be handled. For Eltel, the situation wasn't without its issues. A cloud solution that could evolve at the company's pace and give control over all the details was therefore implemented.
– Today we take decisions based on facts and statistics, not on good assumptions, says Per Schjelderup from Eltel.

The FTTH Conference in Valencia was the start for IS Tools' expansion abroad. We had a chat to Johan Wengelin, marketing director at IS Tools, to get a few words after the conference and to find out why IS Tools will be successful in Europe.

Pages