Outages API - V3
If you have a maintenance window or a scheduled outage for a device then you will likely want to suspend alerting for that device during that period.
NMIS has supported this for a long time, please refer to the NMIS Outages documentation for further information.
Now, it is also possible to manage Outages within the Administration console or API.
Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"
We can view Enterprise Services below using these endpoints - http[s]://server/en/omk/admin/api/v3/outages
API Routes
Each resource has a consistent set of operations
Request Method | Operation | URL Example | id required | Notes |
---|---|---|---|---|
GET | read list | /server/omk/admin/v3/outages | n | Returns a list of Enterprise Services. |
GET | read one | /server/omk/admin/v3/outages/id | y | Returns the details of one Enterprise Service. |
POST | create one | /server/omk/admin/v3/outages | n | Create an Outage for given node or element |
PUT | update one | /server/omk/admin/v3/outages/id | y | Edit an already existing outage data |
DELETE | delete one | /server/omk/admin/v3/outages/id | y | Delete an existing outage |
Authentication
All these methods require authentication.
POST http://server/en/omk/admin/login
Form data:
- username
- password
Get Outages
GET http://server/en/omk/admin/api/v3/outages
Returns a list of outages.
Response:
[ { "change_id": "ticket #1234", "current": "current", "description": "Emergency outage", "element": [ { "element_name": "Vlan2", "node_name": "Switch-1" }, { "element_name": "regex:^Vlan.*?$", "node_name": "Switch-2" } ], "end": 1684156863, "frequency": "once", "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4", "nodes": { "name": [ "Switch-2", "Switch-1" ] }, "options": {}, "start": 1683811263 }, { "change_id": "Outage_123_AT_OPTESTS", "current": null, "description": "Emergency outage", "end": 1683825925, "frequency": "once", "id": "ea7a3a94-f056-432f-91c5-9f39eee7c706", "nodes": { "name": [ "asgard", "apc-ups" ] }, "options": {}, "start": 1646918463 } ]
GET of /v3/outages for List
GET http[s]://server/en/omk/admin/api/v3/outages
If your GET call provides an Accept
header indicating JSON, or if you use a .json
suffix, eg /v3/outages.json
as URI, then It will look for matching Outages and return their properties in the form of a JSON object, an array of Outages.
Successful Response
HTTP Status | Body | Description |
---|---|---|
200 | Possibly empty JSON array of objects | Each array element is a JSON object with the raw properties of the Outages in question, described in known Outage properties. |
Unsuccessful Response
HTTP Status | Body | Description |
---|---|---|
401 Unauthorized | JSON object with an error property | You are not authenticated. |
403 Forbidden | JSON object with an error property | You are not authorized. |
GET of /v3/outages/<id> for Read
If your GET call provides an accept
header indicating application/json
or if you use /en/omk/admin/api/v3/outages/
<id>.json
as URI, then the Outage will be looked up and all properties will be returned in the form of a JSON object.
Successful Response
HTTP Status | Body |
---|---|
200 | JSON object with all known Outage properties. |
Unsuccessful Response
HTTP Status | Body | Description |
---|---|---|
400 Bad Request | JSON object with an error property | |
401 Unauthorized | JSON object with an error property | You are not authenticated. |
404 Not Found | JSON object with an error property | You are authenticated but not authorised to view this Outage. |
404 Not Found | JSON object with an error property | The |
GET http://server/en/omk/admin/api/v3/outages/#ID
Ex. http://server/en/omk/admin/api/v3/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4
Returns an outage.
Response:
{ "change_id": "ticket #1234", "current": "current", "description": "Emergency outage", "element": [ { "element_name": "Vlan2", "node_name": "Switch-1" }, { "element_name": "regex:^Vlan.*?$", "node_name": "Switch-2" } ], "end": 1684156863, "frequency": "once", "id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4", "nodes": {}, "options": {}, "start": 1683811263 }
Outages Properties
The following tables represents the properties of an Outage.
Property | Description | Example |
| A globally unique Outage ID | "63576103ad794974594a1f11" |
change_id | The name of the Enterprise Service. This is used for identifying the Enterprise Service | "John Test" |
current | A long description of the Enterprise Service | "This is a test Enterprise Service" |
description | The name of the node that is created and/or used to store the status and events for the Enterprise Service. | "john_test_ES" |
frequency | How frequently the status of the Enterprise Service is recalculated. | 60 |
start | The time that these status metrics were last recalculated. The metrics are updated with a frequency of frequency seconds. | 1682489067 |
end | The Overall Status can be Up, Degraded or Down. The Overall Status of the Enterprise Service is calculated from the worst of the Node State, Interface State and Service State. | "Down" |
nodes | If any Interface is marked Down, the Interface State is marked Down, otherwise it is Normal. | "Normal" |
element | A decimal number between 0 (bad) and 100 (good) inclusive representing the status of the interfaces in the Enterprise Service. The Interface Status is calculated from the status events for the Interfaces by aggregating all the Interface-related status event levels and averaging them out to a value from 0% to 100%. | 100 |
options | A status level categorizing the interface_status , into traffic light colours. | "Normal" |
Limitations
API Endpoint
All requests are made under the following base URL:
http[s]://server/omk/admin/v3/outages
Examples of how to use the API can be found in the response blocks below. In general, the queries will look something like this: |
GET HTTP://server/omk/opCharts/v2/enterprise_services/63fdd07e0454aa367e368b0b.json ************* OUTPUT **************** { description: "This is a test Enterprise Service", frequency: "30", id: "63fdd07e0454aa367e368b0b", interface_state: "Normal", interface_status: 100, interface_status_level: "Normal", interfaces_reachable: null, interfaces_unreachable: 0, last_updated: 1682489067, name: "John Test", node_name: "john_test_ES", node_state: "Down", node_status: 98.3333333333333, node_status_level: "Minor", nodes_degraded: 1, nodes_down: 1, nodes_total: 3, nodes_up: 1, overall_status: "Down", service_state: "Down", service_status: 0, service_status_level: "Fatal", services_degraded: 0, services_reachable: 0, services_unreachable: 1 } ################################## List ################################## GET HTTP://server/omk/opCharts/v2/enterprise_services.json ************* OUTPUT **************** [ { description: "Show core network", frequency: "60", id: "63f6fda90454aa0265333e61", interface_state: "Normal", interface_status: 100, interface_status_level: "Normal", interfaces_reachable: null, interfaces_unreachable: 0, last_updated: 1682570689, name: "Core Network", node_name: "core_network_es", node_state: "Normal", node_status: 96.6666666666667, node_status_level: "Minor", nodes_degraded: 1, nodes_down: 0, nodes_total: 1, nodes_up: 0, overall_status: "Degraded", service_state: "Normal", service_status: 100, service_status_level: "Normal", services_degraded: 0, services_reachable: 1, services_unreachable: 0 }, { description: "This is a test Enterprise Service", frequency: "30", id: "63fdd07e0454aa367e368b0b", interface_state: "Normal", interface_status: 100, interface_status_level: "Normal", interfaces_reachable: null, interfaces_unreachable: 0, last_updated: 1682489067, name: "John Test", node_name: "john_test_ES", node_state: "Down", node_status: 98.3333333333333, node_status_level: "Minor", nodes_degraded: 1, nodes_down: 1, nodes_total: 3, nodes_up: 1, overall_status: "Down", service_state: "Down", service_status: 0, service_status_level: "Fatal", services_degraded: 0, services_reachable: 0, services_unreachable: 1 } ]