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 `error` property contains an explanation of what went wrong with your request, e.g. if you request a non-existent Outage.

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
`id`	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
  }
]

Space shortcuts

Child pages

Outages API - V3

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

GET of /v3/outages for List

Successful Response

Unsuccessful Response

GET of /v3/outages/<id> for Read

Successful Response

Unsuccessful Response

Outages Properties

Limitations

API Endpoint

Space shortcuts

Child pages

Admin Outages API V3 draft

Outages API - V3

Public API for Outages "http[s]://server/en/omk/admin/api/v3/outages"

Authentication

Get Outages

GET of /v3/outages for List

Successful Response

Unsuccessful Response

GET of /v3/outages/<id> for Read

Successful Response

Unsuccessful Response

Outages Properties

Limitations

API Endpoint