/
Admin Outages API V3 draft

Admin Outages API V3 draft

May 15, 2023

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 Outages 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

Request Method

Operation

URL Example

id required

Notes

GET

read list 

/server/omk/admin/v3/outages

n

Returns a list of Outages.

GET

read one 

/server/omk/admin/v3/outages/id

y

Returns the details of one Outage .

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 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

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

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:

[ { "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/<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

HTTP Status

Body

200

JSON object with all known Outage properties.

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

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 }

 

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

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

HTTP Status

Body

Description

400 Bad Request

JSON object with an error property

The error property contains an explanation of what went wrong
with 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:

{ "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 }

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

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

HTTP Status

Body

Description

400 Bad Request

JSON object with an error property

The error property contains an explanation of what went wrong
with 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:

{ "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 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

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

HTTP Status

Body

Description

400 Bad Request

JSON object with an error property

The error property contains an explanation of what went wrong
with 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.

Outages Properties

The following tables represents the properties of an Outage.

 

Property

Description

Example

id

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",
  "node_name": "Switch-1"
}, {

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

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:

http[s]://server/omk/admin/v3/outages