Skip to end of banner
Go to start of banner

Admin Outages API V3 draft

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

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

GETread list /server/omk/admin/v3/outagesnReturns a list of Enterprise Services.
GETread one /server/omk/admin/v3/outages/idyReturns the details of one Enterprise Service.
POSTcreate one/server/omk/admin/v3/outagesnCreate an Outage for given node or element
PUTupdate one/server/omk/admin/v3/outages/idyEdit an already existing outage data
DELETEdelete one/server/omk/admin/v3/outages/idyDelete 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

200Possibly empty JSON array of objectsEach 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 UnauthorizedJSON object with an error propertyYou are not authenticated.
403 ForbiddenJSON object with an error propertyYou 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

200JSON object with all known Outage properties.

Unsuccessful Response

HTTP Status

Body

Description

400 Bad RequestJSON object with an error property
401 UnauthorizedJSON object with an error propertyYou are not authenticated.
404 Not FoundJSON object with an error propertyYou are authenticated but not authorised to view this Outage.
404 Not FoundJSON 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
}

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

id

A globally unique Outage ID

"63576103ad794974594a1f11"
change_id

Insert any reference number if required in the change id field

ticket #12345"
currentIf the outage is current or scheduled/future outage"current/null"
descriptionLong 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
enddate and time of outage start and end e.g. 2017-10-31T03:04:26+0000



nodesList of nodes for which Outages is defined[ 'Switch-1','Switch-2' ]
elementList of elements from nodes for which Outages are defined.

 [ {

  "element_name": "Vlan2",
  "node_name": "Switch-1"
}, {

   "element_name": "regex:^Vlan.*?$",
   "node_name": "Switch-2"
} ]

optionsoptional 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

  • No labels