Documentation

REST API examples

The following section contains bash script examples on how to perform actions using the SKOOR REST API with the curl utility. Most input and output is formatted in JSON. For readability, the JSON parser jq was used in some of the examples which can be installed from the common Redhat or CentOS repositories.

Bash script header

Common parameters to set as a bash script header for the script examples below (USER and PASSWORD must be adapted to a real SKOOR user):

#!/bin/bash
HOST=reltest
USER=admin
PASSWORD=admin

Request examples

The requests and request bodies in the below examples can be copied and pasted as they are except of the object ids which must be replaced by existing ones on the system the requests are performed. Parts of the request bodies must be provided although not containing meaningful values for object creation or update.

Most of the date and time information in the requests must be provided in ISO 8601 format and duration format

SKOOR Session

Log in to SKOOR:

SESSION_ID=$(curl --silent -k "https://$HOST/skoor-webservice/session/login?username=$USER&password=$PASSWORD" | jq -r '.sessionId') >/dev/null

Please always log out after all reqests are done. Sessions are kept open for 24 hours otherwise

Log out:

curl -k "https://$HOST/skoor-webservice/session/logout?sessionId=$SESSION_ID"

Users

Query all SKOOR users and parse names and roles using jq:

curl --silent -k "https://$HOST/skoor-webservice/users?&sessionId=$SESSION_ID" | jq -r '.[] | "\(.name) \(.role)"'

Groups

Query a specific group with id 495:

curl -k -X GET "https://$HOST/skoor-webservice/groups/495?sessionId=$SESSION_ID"

Query a group using an URL encoded search filter. The result should contain all groups below parent group id 207.

Original search filter: groups with an id not equal to 207:

{"type":"group","mode": "and","conditions": [{"item":"id","operator": "ne","expression":"207"}]}

URL encoded search filter (encoding/decoding can be done using a SKOOR HTTP job or one of several services on the internet):

%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D

Query:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/search?filterDefinition=%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D&sessionId=$SESSION_ID"

Devices

Query device with id 383:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383?sessionId=$SESSION_ID"

Create a device below the group with id 308:

Request body for a device of subtype server with the name SKOOR Server. Set the default collector to Id 2 which is the local collector:

DEVICE_BODY='{
	"type": "device",
	"subType": "server",
	"name": "SKOOR Server",
	"address": "",
	"netmask": "",
	"deviceName": "localhost",
	"properties": [],
	"parameter": {},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"isTemplate": false,
	"instanceType": "sub",
	"collectorId": 2,
	"hasChildren": false
}'

Request:

echo $DEVICE_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/devices?parentType="group"&parentId="308"&sessionId=$SESSION_ID"

Create a device instance from a template below the group with id 332. To achieve this, the copy method of the REST API will be used. The device id (180 in the example) must be set to the id of the device template:

curl -k -X POST "https://$HOST/skoor-webservice/devices/180/copy?destinationName="rest-test"&destinationAddress="localhost"&parentType="group"&parentId=332&destinationType="instance"&collectorId=2&jobsStopped=false&sessionId=$SESSION_ID"

Delete the device with id 558:

Deleted objects can only be restored from config backup!

curl -k -X DELETE "https://localhost/skoor-webservice/devices/558?recursive=true&sessionId=$SESSION_ID"

Jobs

Query job id 1675 with thresholds and values:

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1675?thresholds=true&values=true&sessionId=$SESSION_ID"

Search for a job using a search filter.

URL encoded search filter to search for jobs below the group with id 216 having a custom property with key test_property set to the value of abc:

curl -ks -X GET "https://$HOST/skoor-webservice/groups/216/search?filterDefinition=%7B%22type%22%3A%22job%22%2C%22mode%22%3A%22and%22%2C%22conditions%22%3A%5B%7B%22item%22%3A%22property_key%22%2C%22operator%22%3A%22eq%22%2C%22expression%22%3A%22abc%22%2C%22propertyKey%22%3A%22test_property%22%7D%5D%7D&sessionId=$SESSION_ID"

Plain text search filter for jobs of subtype webcollector below group 310 with result parsed using jq:

curl -ks -X GET -G "https://$HOST/skoor-webservice/groups/310/search?sessionId=$SESSION_ID" --data-urlencode "filterDefinition={\"type\":\"job\",\"mode\":\"and\",\"conditions\":[{\"item\":\"subType\",\"operator\":\"eq\",\"expression\":\"webcollector\"}]}" | jq -r '.items[] | "\(.deviceName) \(.name) \(.id)"'

Create a job below device id 555:

Request body for a job of subtype webcollector with name TEST generated and three return values. Create the job under the device with Id 555. The execution interval will be set to 0 seconds (PT0S: no interval):

JOB_BODY='{
	"type": "job",
	"name": "TEST generated",
	"deviceId": 555,
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valueName": "Return value 1"
			},
			{
				"valueName": "Return value 2"
			},
			{
				"valueName": "Return value 3"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"stateForced": false,
	"thresholds": null,
	"values": null,
	"message": null
}'

Request:

echo $JOB_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs?parentType="device"&parentId="555"&sessionId=$SESSION_ID"

Update job with id 1608:

Request body for the job with id 1608 on device id 555. Set thresholds for this job:

JOB_BODY_UPDATE='{
	"type": "job",
	"id": 1608,
	"name": "Richmond",
	"deviceId": 555,
	"deviceName": "TEST generated device",
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valuePrecision": 3,
				"valueName": "myValue"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"currentState": "ok",
	"stateForced": false,
	"thresholds": {
		"major": {
			"mode": "or",
			"conditions": [
				{
					"key": "returnValue1",
					"operator": ">",
					"value": 60.0,
					"repetition": 1,
					"inFuture": null,
					"adaptiveValues": null
				}
			]
		}
	},
	"values": {},
	"message": null,
	"collectorId": 2
}'

Request:

echo $JOB_BODY_UPDATE | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1608?sessionId=$SESSION_ID"

Stop/start job with id 1605:

curl -ks -X GET -G "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID" | jq -r '.stopped = false' | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID"

Query value history of job id 1326:

Date and time information must be provided in ISO 8601 format and duration format

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1326/value-history?timestamp_begin=2018-04-16T08%3A00%3A00Z&timestamp_end=2018-04-16T10%3A00%3A00Z&scale=PT10M&key=returnValue1&mode=avg&values=true&sessionId=$SESSION_ID"

SLC

Query SLC state history with id 6:

curl -k -X GET "https://$HOST/skoor-webservice/slcs/6/state-history?timestamp_begin=2017-10-01T00:00%2B01:00&timestamp_end=2017-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

SLO

Query SLO with id 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116?sessionId=$SESSION_ID"

Query state history of SLO id 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116/state-history?timestamp_begin=2018-01-01T00:00%2B01:00&timestamp_end=2018-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

Query child objects of SLO id 176:

curl -k -X GET "https://$HOST/skoor-webservice/slos/176/children?sessionId=$SESSION_ID"

Create SLO below group id 296:

Request body for an SLO of subtype top with the name TEST SLO:

SLO_BODY='{
	"type": "slo",
	"subType": "top",
	"name": "TEST SLO",
	"deviceId": 0,
	"deviceName": "",
	"stateOperation": "and",
	"pushState": "any",
	"sortMode": "link",
	"warning": 0,
	"minor": 0,
	"major": 0,
	"minorWarning": 0,
	"minorMinor": 0,
	"warningWarning": 0,
	"isTemplate": false,
	"ignoreMaintenance": true,
	"isReason": true,
	"properties": [],
	"parameters": {
		"children": 0,
		"costsPerMin": 0,
		"currency": "",
		"riskFactor": 0
	},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none"
}'

Request:

echo $SLO_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/slos?parentType=group&parentId=296&sessionId=$SESSION_ID"

Create SLO instance from SLO template with id 179. SLO name will be rest-test-slo and parent object will be the slo with id 177:

curl -k -X POST "https://$HOST/skoor-webservice/slos/179/copy?destinationName=rest-test-slo_1&parentType=slo&parentId=177&destinationType=instance&sessionId=$SESSION_ID"

Outages

Query outages between 2019-02-21T09:00+01:00 and 2019-03-21T23:59+01:00 (URL encoded). Default is a minimum duration of 10 minutes (PT10M) and major state only:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383/outages?begin=2019-02-21T09:00%2B01:00&end=2019-03-21T23:59%2B01:00&recalc=false&sessionId=$SESSION_ID"

Revaluations

Query revaluations of group 207 from 2019-04-01T00:00:00Z:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/revaluations?begin=2019-04-01T00:00:00Z&sessionId=$SESSION_ID"

Add a revaluation to group id 207:

The begin and end parametrs have to be set in UTC followed by the timezone Z or +00:00 or the local time followed by the timezone (e.g. +02:00). The timezone parameter only affects the times array

If the begin parameter time does not match the begin time of the times array, the maintenance will only be displayed in edit mode (Edit revaluation). Please not that MET will automatically distinguish between summer and winter time. Set the begin time to the local time in this case

Request body for a one time revaluation from 2019-04-13T07:20:00Z to 2019-04-13T08:20:00Z:

REVALUATION_BODY='{
	"begin": "2019-04-13T07:20:00Z",
	"end": "2019-04-13T08:20:00Z",
	"created": null,
	"type": "maintenance",
	"adjustTo": "undefined",
	"inPast": null,
	"incident": null,
	"name": "Test-Maintenance",
	"active": [
		{
			"type": "one_time",
			"name": null,
			"timezone": "UTC",
			"times": [
				{
					"begin": "07:20",
					"duration": "PT1H",
					"date": "2019-04-13"
				}
			],
			"exception": false
		}
	]
}'

Request:

echo $REVALUATION_BODY | curl -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/groups/207/revaluations?sessionId=$SESSION_ID"
Previous
SKOOR Webservice
Next
REST API for Dashboard Export