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.
...
Request Method | Operation | URL Example | id required | Notes |
---|---|---|---|---|
GET | read list | /server/omk/admin/v3/outages | n | Returns a list of Enterprise ServicesOutages. |
GET | read one | /server/omk/admin/v3/outages/id | y | Returns the details of one Enterprise ServiceOutage . |
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 |
...
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.
...
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.
...
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.
...
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:
...
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 wrongwith 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
...
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 wrongwith 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
...
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 wrongwith 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.
...
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" |
...