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.
The v3 api has added support for "ELEMENT OUTAGES" and this is not backward compatible with v2 api. If you make a v2 api call, it will not return any outages that are "ELEMENT OUTAGES".
See ALL ABOUT ELEMENT OUTAGES
Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"
We can view Enterprise Services Outages below using these endpoints - http[s]://server/en/omk/admin/api/v3/outages
...
Request Method | Operation | URL Example | id required | Notes |
|---|---|---|---|---|
| GET | read list | /server/omk/admin/v3/outages | n | Returns a list of Enterprise ServicesOutages. |
| GET | read one | /server/omk/admin/v3/outages/id | y | Returns the details of one Enterprise ServiceOutage . |
| 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 of /v3/outages for List
GET http[s]
...
://server/en/omk/admin/api/v3/outages
Returns a list of outages.
Response:
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 http://server/en/omk/admin/api/v3/outages
Returns a list of outages.
Response:
| Code Block |
|---|
[
{ |
| Code Block |
[ { "change_id": "ticket #1234", "current": "current", "description": "Emergency outage", "elementchange_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/<id> for Read
GET /omk/opCharts/v2/enterprise_services
If your GET call provides an Acceptaccept header indicating JSON, application/json or if you use a .json suffix, eg /v2/enterprise_services/en/omk/admin/api/v3/outages/<id>.json as URI, then opCharts will look for matching Enterprise Services and return their properties the Outage will be looked up and all properties will be returned in the form of a JSON object, an array of Enterprise Services. Extra query parameters can be used to narrow down the listing or search for particular Enterprise Services only; without parameters you will get all Enterprise Services.
Optional Query Parameters
...
Parameter
...
Description
...
Search criteria for matching Enterprise Services. The search expression is a hash of field-name, search value pairs.
Example:
http://athena.opmantek.net/en/omk/opCharts/v2/enterprise_services.json?search={"name":"John%20Test"}
You can use "regex:<regular expression>" or a plain text string, or iregex: for case-insensitive regex.
Successful Response
...
HTTP Status
...
Body
...
Description
...
Successful Response
HTTP Status | Body |
|---|---|
| 200 | JSON object with all known Outage properties. |
Unsuccessful Response
Unsuccessful Response
HTTP Status
Body
Description
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 |
GET of /v2/enterprise_services/<id> for Read
If your GET call provides an accept header indicating application/json or if you use /omk/opCharts/v2/enterprise_services/<id>.json as URI, then the Enterprise Service will be looked up and all properties will be returned in the form of a JSON object.
Successful Response
...
HTTP Status
...
Body
...
Unsuccessful Response
...
HTTP Status
...
Body
...
Description
...
The error property contains an explanation of what went wrong
with your request, e.g. if you request a non-existent Enterprise Service.
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:
| Code Block |
|---|
{
"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
} |
POST of /v3/outages/ for Create
Create an Outage by sending a pay-load JSON object and this will create an Outage on your system and send an appropriate response.
Successful Response
HTTP Status | Body | Description |
|---|---|---|
| 201 | JSON object with success and id properties | The success property is set to 1 and only if the request was successful. The id property is the new event's ID |
Unsuccessful Response
HTTP Status | Body | Description |
|---|---|---|
| 400 Bad Request | JSON object with an error property | The error property contains an explanation of what went wrongwith your request, e.g. if your payload is of wrong format to create an Outage. |
| 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 create an Outage. |
Create Outage
POST http://server/en/omk/admin/api/v3/outages
Returns 201 if the outage was successfully created.
Payload example:
| Code Block |
|---|
{
"change_id": "ticket #1234",
"description": "Emergency outage",
"nodes": ["Switch-2","Switch-1"],
"elements" : [
{ "node_name": "Switch-1",
"element_name" : "Vlan2"
},
{ "node_name": "Switch-2",
"element_name" : "regex:^Vlan.*?$"
}
],
"start": "11-May-2023 23:21:03",
"end": "15-May-2023 23:21:03"
} |
Return
| Code Block |
|---|
{
"id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
"success": 1
} |
PUT of /v3/outages/<id> for Update
Create an Outage by sending a pay-load JSON object and this will create an Outage on your system and receive an appropriate response.
Successful Response
HTTP Status | Body | Description |
|---|---|---|
| 201 | JSON object with success and id properties | The success property is set to 1 and only if the request was successful. The id property is the new event's ID |
Unsuccessful Response
HTTP Status | Body | Description |
|---|---|---|
| 400 Bad Request | JSON object with an error property | The error property contains an explanation of what went wrongwith your request, e.g. if your payload is of wrong format to edit an Outage. |
| 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 create an Outage. |
Update Outage
PUT http://server/en/omk/admin/api/v3/outages/#ID
Returns 200 if the outage was successfully updated.
Payload example:
| Code Block |
|---|
{
"change_id": "ticket #1234",
"description": "Emergency outage",
"nodes": ["Switch-2","Switch-1"],
"elements" : [
{ "node_name": "Switch-1",
"element_name" : "Vlan222"
},
{ "node_name": "Switch-2",
"element_name" : "regex:^Vlan.*?$"
}
],
"start": "11-May-2023 23:21:03",
"end": "15-May-2023 23:21:03"
} |
Return
| Code Block |
|---|
{
"id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
"success": 1
} |
Delete of /v3/outages/<id> for Create
Create an Outage by sending a pay-load JSON object and This will create an Outage on your system and receive an appropriate response.
Successful Response
HTTP Status | Body | Description |
|---|---|---|
| 200 | JSON object with success | The success property is set to 1 and only if the request was successful. |
Unsuccessful Response
HTTP Status | Body | Description |
|---|---|---|
| 400 Bad Request | JSON object with an error property | The error property contains an explanation of what went wrongwith your request, e.g. if your id does not exist of wrong id format. |
| 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 delete an Outage. |
Delete Outage
DELETE http://server/en/omk/admin/api/v3/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4
Returns 200 if the outage was successfully removed.
| Anchor | ||||
|---|---|---|---|---|
|
The following tables represents theproperties of an Outage.
Property | Description | Example |
| A globally unique Outage ID | 0ea7644e-b6fa-4fa2-9b33-a86b79db21a4 |
change_id | Insert any reference number if required in the change id field | ticket #12345 |
current | If the outage is current or scheduled/future outage. IS THIS 'currrent' for scheduled or null for future. | current |
description | Long description of an Outage | This is a test outage |
frequency | one of 'once', 'daily', 'weekly' or 'monthly' | once |
start | date and time of outage start. See XYZ for description of allowed values. | 2023-10-31T03:00:00+0000 |
end | date and time of outage end. See XYZ for description of allowed values. | 2023-10-31T03:30:00+0000 |
nodes | List of nodes for which Outages is defined. IS THIS MANDATORY? | [ 'Switch-1','Switch-2' ] |
element | List of elements from nodes for which Outages are defined. IS THIS MANDATORY? DOCUMENT REGEX OR SEE LINK CAN I DO NODE REGEX? | [ { "element_name": "Vlan2", "element_name": "regex:^Vlan.*?$", |
options | optional key=values to adjust NMIS behaviour during an outage DOCUMENT THE KEYS AND VALUES | "Normal" |
Limitations
API Endpoint
All requests are made under the following base URL:
| Code Block |
|---|
http[s]://server/omk/admin/v3/outages
|
Enterprise Service properties
...
Property
...
Description
...
Example
...
id
...
A globally unique Enterprise Service ID
...
The time that these status metrics were last recalculated. The metrics are updated with a frequency of frequency seconds.
...
A decimal number between 0 (bad) and 100 (good) inclusive representing the status of the nodes in the Enterprise Service.
The Node Status is calculated from the status events for the Nodes. It aggregates the status event levels and presents an average of 0% to 100%
...
A decimal number between 0 (bad) and 100 (good) inclusive representing the status of the interfaces in the Enterprise Service.
The Service Status is calculated from the status events for the Services. It aggregates the status event levels and presents an average of 0% to 100%
...
Limitations
API Endpoint
All requests are made under the following base URL:
| Code Block |
|---|
http[s]://server/omk/opCharts/v2/enterprise_services
|
...
| Code Block |
|---|
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
}
] |