Using the RESTful API

The Operations Manager features an REST API-first design, whereby the API is built first and the Operation Manager's Web UI and CLI (ogcli) are simply clients of that API. This means everything you can accomplish manually via the UI or CLI, you can accomplish programmatically using the API.

Examples on how to use the API are provided for cURL and Python. Before you start, ensure you have these tools installed locally, e.g. on your Linux, macOS or Windows (with WSL) machine.

Authenticate

To access the API, you must first authenticate the same username and password you use to log in to the web UI or CLI – this may be a local or remote AAA account.

This initial authentication step generates a session token, which is then passed via the headers to authenticate subsequent requests. Note that the token will expire using the timeout set for the Web UI.

Run these commands, replacing the OM_* variable values with those appropriate for your Operations Manager.

OM_ADDRESS=192.168.0.1
OM_USERNAME=root
OM_PASSWORD=default
TOKEN=$(curl -k "https://$OM_ADDRESS/api/v2/sessions" -X POST -H 'Content-Type: application/json' -d '{"username":"'$OM_USERNAME'","password":"'$OM_PASSWORD'"}' | jq '.sid' | tr -d '\"')

Check the value of token looks something like:

echo $TOKEN
550e3f46b1c82c711eabc242ac130003

Now you've obtained a session token, you perform any permitted API operation for that user. Examples follow.

Example: Get Operations Manager Version

curl -k -X GET "https://$OM_ADDRESS/api/v2/system/version" -H "Authorization: Token $TOKEN" | jq '.'

Example: Create a Local Admin User

Structure the required fields into JSON format:

read -r -d '' JSON << 'EOF'
{
 "user": {
 "enabled": true,
 "username": "adal",
 "description": "Ada Lovelace",
 "no_password": false,
 "password": "default",
 "groups": [ "groups-1" ]
 }
}
EOF

POST the JSON to the users API endpoint:

curl -k -X POST "https://$OM_ADDRESS/api/v2/users/" -H "Authorization: Token $TOKEN" -H 'Content-Type: application/json' -d "$JSON" | jq '.'

Example: Disable the root User

Structure the required fields into JSON format:

read -r -d '' JSON << 'EOF'
{
 "user": {
 "username": "root",
 "description": "System wide SuperUser account",
 "enabled": false,
 "no_password": false,
 "groups": [ "groups-1" ]
 }
}
EOF

PUT the JSON to the users/users-1 (this is the default config ID of the root user) API endpoint:

curl -k -X PUT "https://$OM_ADDRESS/api/v2/users/users-1" -H "Authorization: Token $TOKEN" -H 'Content-Type: application/json' -d "$JSON" | jq '.'

Example: Python

From any system with Python and the Requests libraries installed, start the Python interpreter or create a script and run:

import requests, json
data = { 'username' : 'root', 'password' : 'default' }
r = requests.post('https://address.of.opengear/api/v2/sessions/', data=json.dumps(data), verify=False)
token = json.loads(r.text)['session']

Now you can send subsequent requests (e.g. a GET request to https://address.of.opengear/api/v2/users/ for Console Servers) setting your token in the headers:

headers = { 'Authorization' : 'Token ' + token }
r = requests.get('https://address.of.opengear/api/v2/users/', headers=headers, verify=False)
j = json.loads(r.text)
print(json.dumps(j, indent=4))