Outages API - V3

...

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

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

GET http[s]://serverIf your GET call provides an accept header indicating application/json or if you use /en/omk/admin/api/v3/outagesIf your GET call provides an Accept header indicating JSON, or if you use a .json suffix, eg /v3/outages/<id>.json as URI, then It will look for matching Outages 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 Outages.

Successful Response

HTTP Status	BodyDescription
200Possibly empty JSON array of objects	Each array element is a JSON object with the raw properties of the Outages in question, described inall 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.

403 Forbidden

404 Not Found JSON object with an error property You are

not authorized.

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

...

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

...

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

...

#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",
    "current": "current",       "descriptionnode_name": "Emergency outage",Switch-1"
       "element": [ },
        {
            "element_name": "Vlan2regex:^Vlan.*?$",
            "node_name": "Switch-12"
        },
    ],
   { "end": 1684156863,
    "frequency": "once",
    "element_nameid": "regex:^Vlan.*?$",
       0ea7644e-b6fa-4fa2-9b33-a86b79db21a4",
    "node_namenodes": "Switch-2"
        }
    ]{},
    "endoptions": 1684156863{},
    "frequencystart": "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:

Code Block
{ "change_id": "ticket #1234", "description": "Emergency outage", "nodes": ["Switch-2","Switch-1"]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 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 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:

Code Block

{
    "change_id": "ticket #1234",
    "elementsdescription" : ["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 }

Update Outage

...

PUT of /v3/outages/

...

Returns 200 if the outage was successfully updated.

Payload example:

...

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

Code Block

{
    "change_id": "ticket #1234",
    "elementsdescription" : "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 }

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

Anchor
properties
properties
Outages Properties

...

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"
`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", "node_name": "Switch-1" }, { "element_name": "regex:^Vlan.*?$", "node_name": "Switch-2" } ]
`options`	optional key=values to adjust NMIS' behaviour during an outageo	"Normal"

...

Versions Compared

Old Version 8

New Version 9

Key

Outages API - V3

Get Outages

GET of /v3/outages for List

Successful Response

Unsuccessful Response

GET of /v3/outages/<id> for

Read

Successful Response

Unsuccessful Response

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

Successful Response

Unsuccessful Response

Create Outage
POST http://server/en/omk/admin/api/v3/outages

POST of /v3/outages/ for Create

Successful Response

Unsuccessful Response

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Update Outage

PUT of /v3/outages/

<id> for Create

Successful Response

Unsuccessful Response

Update Outage

Return

Return

Delete of /v3/outages/<id> for Create

Successful Response

Unsuccessful Response

Delete Outage

Anchor
properties
properties
Outages Properties

Page Comparison

Versions Compared

Old Version 8

New Version 9

Key

Get Outages

GET of /v3/outages for List

Successful Response

Unsuccessful Response

GET of /v3/outages/<id> for

Read

Successful Response

Unsuccessful Response

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

Successful Response

Unsuccessful Response

Create OutagePOST http://server/en/omk/admin/api/v3/outages

POST of /v3/outages/ for Create

Successful Response

Unsuccessful Response

Create OutagePOST http://server/en/omk/admin/api/v3/outages

Update Outage

PUT of /v3/outages/

<id> for Create

Successful Response

Unsuccessful Response

Update Outage

Return

Return

Delete of /v3/outages/<id> for Create

Successful Response

Unsuccessful Response

Delete Outage

AnchorpropertiespropertiesOutages Properties

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Create Outage
POST http://server/en/omk/admin/api/v3/outages

Anchor
properties
properties
Outages Properties