Maintenance periods in the API

There is a specific set of API methods for manipulating maintenance periods for a monitor or for all monitors in a monitor group.

Maintenance period object description

The following MaintenancePeriod object is used in the API methods described below:

Name	Description	Data type
`Id`	The unique identifier for this maintenance period	Integer
`ScheduleMode`	OneTime, Daily, Weekly or Monthly	Enum
`StartDateTime`	A start date and time (only applicable to a One-time scheduled period)	DateTime
`EndDateTime`	The end date and time of a One-time scheduled maintenance period	DateTime
`StartTime`	The start time (“HH:mm”, which is 24-hour notation) for a recurring (Daily, Weekly or Monthly) maintenance period	String (“HH:mm”)
`EndTime`	The end time (“HH:mm”, which is 24-hour notation) for a recurring (Daily, Weekly or Monthly) maintenance period	String (“HH:mm”)
`WeekDay`	The day of the week for a weekly maintenance period (Sunday/Monday/[…]/Saturday)	Enum
`MonthDay`	The day number for a monthly maintenance period	Int (1-31)
`MaintenanceType`	DisableMonitoring (to disable the monitor altogether) or DisableNotifications (monitoring will still occur, but notifications will not be sent)	Enum

When a maintenance period is returned through the API, all properties will be present, but depending on the ScheduleMode, some fields related to start and end dates/times will not be used.

For a one-time maintenance period, we will need to know the start and end date and time, so the StartDateTime and EndDateTime properties will be used. For recurring maintenance periods, the start and end time fields are appropriate, and, depending on the schedule type, the WeekDay or MonthDay property.

For example, a daily schedule would look like this:

{
"Id": 123, 
"ScheduleMode": "Daily", 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications"
}

The properties that are not relevant for this schedule type (DateTime, WeekDay and MonthDay) are left out.

A weekly schedule would look like this:

{
"Id": 123, 
"ScheduleMode": "Weekly", 
"WeekDay": "Thursday", 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications"
}

A monthly schedule would look like this:

{
"Id": 125, 
"ScheduleMode": "Monthly", 
"MonthDay": 24, 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications" 
}

A one-time schedule would look like this:

{
"Id": 124, 
"ScheduleMode": "OneTime", 
"StartDateTime": "2018-09-24T22:00",
"EndDateTime": "2018-09-24T22:00", 
"MaintenanceType": "DisableMonitoring" 
}

Maintenance period endpoints

The following API endpoints are available:

Request type	Endpoint	Usage
GET	`Monitor/{monitorGuid}/MaintenancePeriod`	Finds all maintenance periods for a monitor.
POST	`Monitor/{monitorGuid}/MaintenancePeriod`	Saves the new maintenance period provided for the specified monitor
PUT	`Monitor/{monitorGuid}/MaintenancePeriod/{maintenancePeriodId}`	Updates the specified maintenance schedule for the specified monitor
DELETE	`Monitor/{monitorGuid}/MaintenancePeriod/{maintenancePeriodId}`	Deletes the specified maintenance period from the specified monitor
POST	`Monitor/{monitorGuid}/MaintenancePeriod/Cleanup/{beforeDate}`	Clears out all one-time maintenance periods for the specified monitor older than the specified date
POST	`MonitorGroup/{monitorGroupGuid}/MaintenancePeriod`	Adds the provided maintenance period to all monitors in the group specified

GET Monitor

GET Monitor/{monitorGuid}/MaintenancePeriod

This GET request will return a collection containing all maintenance periods scheduled for the monitor with the GUID provided.

Example output:

[
{
"Id": 125, 
"ScheduleMode": "Monthly", 
"MonthDay": 24, 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications"
}, 
{
"Id": 123, 
"ScheduleMode": "Weekly", 
"WeekDay": "Thursday", 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications"
}
]

POST Monitor

POST Monitor/{monitorGuid}/MaintenancePeriod

This method will create the maintenance period provided in the request body and assign it to the monitor with the provided GUID.

A POST request expects an object structure as supplied in the examples under “Maintenance period object description”. As shown there, the structure is dependent on the maintenance period type (OneTime, Daily, Weekly or Monthly). Furthermore, the Id field should not be supplied. A new Id value will be generated automatically.

PUT Monitor

PUT Monitor/{monitorGuid}/MaintenancePeriod/{maintenancePeriodId}

This method will update the maintenance period with the supplied maintenance period ID to the values as supplied in the request body.

Expected input (example for a monthly maintenance-period):

{
"Id": 125, 
"ScheduleMode": "Monthly", 
"MonthDay": 24, 
"StartTime": "22:00", 
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications" 
}

Please note that the Id of the maintenance period has to be supplied in the body as well as in the maintenancePeriodId parameter. If the Id in the parameter does not match the Id of the maintenance period in the request body, an exception will be returned.

DELETE Monitor

DELETE Monitor/{monitorGuid}/MaintenancePeriod/{maintenancePeriodId}

This method will delete the maintenance period with the Id specified in maintenancePeriodId from the monitor with the supplied monitorGuid.

POST Monitor

POST Monitor/{monitorGuid}/MaintenancePeriod/Cleanup/{beforeDate}

This method will remove all one-time schedules with a StartDateTime prior to the date supplied in beforeDate from the monitor with the supplied monitorGuid.

POST MonitorGroup

POST MonitorGroup/{monitorGroupGuid}/MaintenancePeriod

This method will add the maintenance period supplied in the request body to all monitors in the monitor group with the supplied monitor group Guid.

Expected input (example for a weekly maintenance period):

{
"ScheduleMode": "Weekly", 
"WeekDay": "Thursday", 
"StartTime": "22:00",
"EndTime": "22:30", 
"MaintenanceType": "DisableNotifications"
}