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
}
Create Outage
POST http://server/en/omk/admin/api/v3/outages
Returns 201 if the outage was successfully created.
Payload example:
{
"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
{
"id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
"success": 1
}
Update Outage
PUT http://server/en/omk/admin/api/v3/outages/#ID
Returns 200 if the outage was successfully updated.
Payload example:
{
"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
{
"id": "0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
"success": 1
}
Delete Outage
DELETE http://server/en/omk/admin/api/v3/outages/0ea7644e-b6fa-4fa2-9b33-a86b79db21a4
Returns 200 if the outage was successfully removed.
Outages Properties
The following tables represents the properties of an Outage.
Property | Description | Example |
| A globally unique Outage ID | "63576103ad794974594a1f11" |
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 | "current/null" |
description | Long description of an Outage | "This is a test outage" |
frequency | one of 'once', 'daily', 'weekly' or 'monthly' | |
start | date and time of outage start and end | e.g. 2017-10-31T03:04:26+0000 |
end | date and time of outage start and end | e.g. 2017-10-31T03:04:26+0000 |
nodes | List of nodes for which Outages is defined | [ 'Switch-1','Switch-2' ] |
element | List of elements from nodes for which Outages are defined. | [ { "element_name": "Vlan2", "element_name": "regex:^Vlan.*?$", |
options | optional key=values to adjust NMIS' behaviour during an outageo | "Normal" |
Limitations
API Endpoint
All requests are made under the following base URL:
http[s]://server/omk/admin/v3/outages