OP5 Monitor ["OP5 Monitor"]
["Technical Reference", "API"]

OP5 Monitor API

Overview

This page provides a basic description of the OP5 Monitor API, which is covered in detail in the API reference documentation you can find on your server.

Note: The online documentation does not include the Nachos API endpoints, so they are described in detail in this section.

OP5 Monitor includes a REST API. You can use the API to:

  • Retrieve status information.
  • Retrieve report data.
  • Update the OP5 Monitor configuration.

Response format

The API returns responses in HTML, JSON, or XML format.

Authentication modules

When you have more than one OP5 Monitor authentication module, you need to specify which module you are calling. This is done with the dollar character ($).

This standard example calls the default authentication module:

curl -u user:password https://<op5_server_address>/api/filter/query?query=[hosts]

To call the LDAP authentication module, the query is as follows:

curl -u 'user$LDAP:password' https://<op5_server_address>/api/filter/query?query=[hosts]

To call the local authentication module, the query is as follows:

curl -u 'user$Local:password' https://<op5_server_address>/api//filter/query?query=[hosts]

Note that the dollar sign may require single quotes ('$'), depending on the environment.

For more information about authentication modules, see Authentication modules in Manage authentication.

Get started

The API reference documentation is available on your OP5 Monitor server, at the following location: https://<op5_server_address>/api/help/command.

You need to log in with your OP5 Monitor credentials to access the documentation.

Filter API

You can use the filter API to retrieve information and statuses about hosts, services, traps, logs, and more, using filters. If you are already familiar with the OP5 Monitor list view syntax, you can create filter queries with minimal character replacements: %20 for space, for example.

For more information about filter syntax, see Manage list view filters.

The two types of filter query you can run are described below.

Filter

You use the filter part to retrieve a list of objects returned by a filter.

The following example retrieves a list of hosts that are not in OK state:
https://<op5_server_address>/api/filter/query?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked 

Count

You use the count part to return the count of objects in the filter search.

The following example retrieves a count of the objects using the same query as above:
https://<op5_server_address>/api/filter/count?query=[hosts]%20state!=0&columns=name,state,acknowledged,has_been_checked 

Example filter query

This example query retrieves hosts that are down, not acknowledged, and not in scheduled downtime:

https://demo.op5.com/api/filter/query?query=[hosts]%20state!=0%20&%20acknowledged=0%20&%20scheduled_downtime_depth=0

For more information about the filter API, see: https://<op5_server_address>/api/help/filter

Configuration API

You can use the configuration API to update object configuration. It uses the same configuration database as the OP5 Monitor user interface. Objects changed by the API are also visible within the user interface configuration. You can use the API to integrate OP5 Monitor with other third-party software.

For more information about the configuration API, see: https://<op5_server_address>/api/help/config

Remove a custom variable from an object

To completely remove a custom variable from the database, perform a PATCH API call with the custom variable bearing the value null.

Example request

curl -u 'your_username:your_password' -k https://<op5_server_address>/api/config/host/hostname -X PATCH -H "content-type: application/json" -d '{"_CUSTOMVAR": null}'

After sending the PATCH request, save your changes. You can do this by clicking Save in the Configuration page, or by API call:

curl -u 'your_username:your_password' -k https://<op5_server_address>/api/config/change -X POST

Command API

You can use the command API to submit commands to OP5 Monitor.

For more information about the command API, see: https://<op5_server_address>/api/help/command

Report API

You can use the report API to retrieve report data in either XML or JSON format.

For more information about the report API, see: https://<op5_server_address>/api/help/report

Magellan API

You can use the Magellan API to manage Autodiscovery jobs and executions. For more information about Autodiscovery, see Using Autodiscovery to find hosts on your network in Manage hosts and services.

For a complete reference of the Magellan API endpoints, see https://<op5_server_address>/api/help/magellan

Nachos API

You can use Nachos for export configuration.

How Nachos export works

When you send a request to the Nachos endpoint, it returns a response and the export is executed in the background.

Error responses

Error responses are returned for all requests that do not result in 2xx or 3xx statuses. The error is in JSON format and always contains a name and description of the error.

Error responses follow the general structure shown below.

[
  {
     "name": "error_name",
     "description": "error_description",
  }
]

GET latestexport

Retrieves details about the last executed export.

Example request

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/latestexport

Example response

200 — OK

{
	"id": "123e4567-e89b-12d3-a456-426655440045",
	"creation_time": 1982549018,
       "status": "running",
	"status_details": [
	 {
	    "state": "backup",
	    "progress": 1.0,
	    "details": ""
	 },
	 {
	    "state": "config_generation",
	    "progress": 0.0,
	    "details": "writing hosts.cfg"
	 },
	 {
	    "state":"verification",
	    "progress":0.0,
	    "details":""
	 },
	 {
	    "state":"commit",
	    "progress":0.0,
	    "details":""
	 }
	 ],
	    "user": "your_username",
	    "export_type": "user_export"
}

GET exports

Retrieves a list of existing exports, ordered by creation time.

Query parameters

Parameter Data type Description
limit integer

Limits the exports returned to the most recent exports corresponding to the number.

Example: /v1/exports?limit=20

sort_by string

Sort property for exports.

Possible values: id, creation_time, status, user, export_type, details

Example: v1/exports?sort_by=status

order  

Sort order for exports.

Possible values: asc, desc

Example request

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

Example response

200 — OK

[
  {
    "creation_time": "2019-03-26T12:48:07.000000",
    "export_type": "full_export",   
    "id": "37cba483-6f01-4820-b663-6168a44e3771",     
    "status": "running",  
    "status_details": [
       {
		"details": "",
		"progress": 1,
		"state": "backup"
	},
	{
		"details": "",
		"progress": 0,
		"state": "config_generation"
	},
	{
		"details": "",
		"progress": 0,
		"state": "verification"
	},
	{
		"details": "",
		"progress": 0,
		"state": "commit"
	}
		      ],
		"user": "your_username"
	},
	{
		"creation_time": "2019-03-26T12:46:59.000000",
		"export_type": "full_export",
		"id": "1e0a04e7-5ad1-425b-b12b-6082ee07e1c6",
		"status": "success",
		"status_details": [
	                {
				"details": "",
				"progress": 1,
				"state": "backup"
			},
			{
				"details": "",
				"progress": 1,
				"state": "config_generation"
			},
			{
				"details": "",
				"progress": 0,
				"state": "verification"
		        },
			{
				"details": "",
				"progress": 1,
				"state": "commit"
			}
				],
	"user": "your_username"
   }
]

GET exports/<id>

Retrieves an existing export.

Example request

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports/37cba483-6f01-4820-b663-6168a44e3771

Example response

200 — OK

{
	"creation_time": "2019-03-26T12:48:07.000000",
	"export_type": "full_export",
	"id": "37cba483-6f01-4820-b663-6168a44e3771",
	"status": "success",
	"status_details": [
	  {
		"details": "",
		"progress": 1,
		"state": "backup"
	  },
	  {
		"details": "",
		"progress": 1,
		"state": "config_generation"
	  },
	  {
		"details": "",
		"progress": 0,
		"state": "verification"
	  },
	  {
		"details": "",
		"progress": 1,
		"state": "commit"
	  }
			  ],
	"user": "your_username"
}

POST exports

Creates a new export based on the supplied JSON data in the request body. The POST request must supply the header: Content-Type: application/json

Request body

{
  "user": "your_username",
  "export_type": "full_export"|"user_export"
}

Example request

curl -H "Content-Type: application/json" -X POST -d '{"user": "your_username", "export_type": "full_export"|"user_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

Example response

On successful export creation, it returns the created export along with a location header with a URL to the new export resource.

202 - Accepted

{
	"export_type": "full_export",
	"status_details": [
	  {
		"state": "backup",
		"progress": 0,
		"details": ""
	  },
	  {
	        "state": "config_generation",
		"progress": 0,
		"details": ""
         },
	  {
	        "state": "verification",
		"progress": 0,
		"details": ""
	  },
	  {
		"state": "commit",
		"progress": 0,
		"details": ""
	  }
	                   ],
	"id": "6f568330-a79f-4f28-b258-6b1ab0fa745b",
	"creation_time": "2019-03-26T12:57:26.131865",
	"user": "administrator",
	"status": "pending"
}

401 — Unauthorised

curl -H "Content-Type: application/json" -X POST -d '{"user": "not_your_username", "export_type": "full_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

503 — Service unavailable

If the service is busy exporting data, the Retry-After header is set to a number of seconds.