Jump to

• Request
• Response

List blackouts by supported criteria

get

https://EM_HOST:EM_CONSOLE_HTTPS_PORT/em/api/blackouts

Lists blackouts by the supplied criteria.

Request

Query Parameters

• include: string
  Used to include extra information in the result. Right now the only value allowed is "total" which will computes total number of blackouts matching the criteria.

  Example:

  total

• limit: integer(int32)
  Minimum Value: 1

  Maximum Value: 2000

  to limit the number of rows returned. If the result set is greater follow the previous and next links in the results.

  Example:

  20

• name: array[string]
  name of the blackout
• nameMatches: array[string]
  Name pattern of the blackout
• owner: array[string]
  Owner of the blackout
• page: string
  system generated page token used in the self, next and previous links.
• reason: array[string]
  Reason for the blackout
• sort: string
  The sort field and direction. Allowed sort fields are "name", "status", "id", "timeToStart" and "timeToEnd". Allowed directions are ASC and DESC. Default is "name:ASC".

  Example:

  status:ASC,name:DESC

• status: array[string]
  Status of the blackout (SCHEDULED, START_PROCESSING, START_PARTIAL, START_FAILED, STARTED, STOP_PENDING, STOP_FAILED, STOP_PARTIAL, EDIT_FAILED, EDIT_PARTIAL, EDIT_PENDING, STOPPED, ENDED, END_PARTIAL)
• targetId: string
  Used to only list blackouts which have the target of the given id as direct blackout member.

  Example:

  ADLKFIDYFSDHFISDOFSDF

• timeToEndAfter: string
  Start of time period for when blackouts are scheduled to end. Timestamps are with minute accuracy and can provide timezone.

  Example:

  2021-03-01T21:23+01:00

• timeToEndBefore: string
  End of time period for when blackouts are scheduled to end. Timestamps are with minute accuracy and can provide timezone.

  Example:

  2021-03-01T21:23+01:00

• timeToStartAfter: string
  Start of time period for when blackouts are scheduled to start. Timestamps are with minute accuracy and can provide timezone.

  Example:

  2021-03-01T21:23+01:00

• timeToStartBefore: string
  End of time period for when blackouts are scheduled to start. Timestamps are with minute accuracy and can provide timezone.

  Example:

  2021-03-01T21:23+01:00

• type: array[string]
  Type of the blackout, valid values are PATCHING, NOTIFICATION or NOTIFICATION_MAINTENANCE

There's no request body for this operation.

Back to Top

Response

Supported Media Types

• application/json

200 Response

OK

Body ()

Root Schema : BlackoutCollection

Type: object

This is the representation of a list of blackout summaries.

Show Source

• count(required): integer
  Number of blackouts in this page

  Example: 1
• items(required): array items
  Blackout summaries
• links(required): object links
  Result set navigation links.
• total: integer
  Total number of blackouts in this request. This has to be explicitly included in the request.

{
    "x-em-sdk-level":"emSDK",
    "description":"This is the representation of a list of blackout summaries.",
    "type":"object",
    "required":[
        "items",
        "links",
        "count"
    ],
    "properties":{
        "count":{
            "type":"integer",
            "description":"Number of blackouts in this page",
            "example":1
        },
        "total":{
            "type":"integer",
            "description":"Total number of blackouts in this request. This has to be explicitly included in the request."
        },
        "items":{
            "type":"array",
            "description":"Blackout summaries",
            "items":{
                "$ref":"#/components/schemas/BlackoutSummary"
            }
        },
        "links":{
            "type":"object",
            "description":"Result set navigation links.",
            "properties":{
                "self":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the current page in the result set."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts?page=THIS_PAGE_TOKEN"
                            }
                        }
                    ]
                },
                "previous":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the previous page in the result set."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts?page=THE_PREVIOUS_PAGE_TOKEN"
                            }
                        }
                    ]
                },
                "next":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the next page in the result set."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts?page=THE_NEXT_PAGE_TOKEN"
                            }
                        }
                    ]
                }
            }
        }
    }
}

Nested Schema : items

Type: array

Blackout summaries

Show Source

• Array of: object BlackoutSummary
  This is the representation of the Blackout summary.

{
    "type":"array",
    "description":"Blackout summaries",
    "items":{
        "$ref":"#/components/schemas/BlackoutSummary"
    }
}

Nested Schema : links

Type: object

Result set navigation links.

Show Source

• next: next
• previous: previous
• self: self

{
    "type":"object",
    "description":"Result set navigation links.",
    "properties":{
        "self":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Link"
                },
                {
                    "description":"Link to the current page in the result set."
                },
                {
                    "example":{
                        "href":"/em/api/blackouts?page=THIS_PAGE_TOKEN"
                    }
                }
            ]
        },
        "previous":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Link"
                },
                {
                    "description":"Link to the previous page in the result set."
                },
                {
                    "example":{
                        "href":"/em/api/blackouts?page=THE_PREVIOUS_PAGE_TOKEN"
                    }
                }
            ]
        },
        "next":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Link"
                },
                {
                    "description":"Link to the next page in the result set."
                },
                {
                    "example":{
                        "href":"/em/api/blackouts?page=THE_NEXT_PAGE_TOKEN"
                    }
                }
            ]
        }
    }
}

Nested Schema : BlackoutSummary

Type: object

This is the representation of the Blackout summary.

Show Source

• id(required): string
  Blackout ID

  Example: D91786E288D35455C3ADA1B329B49BB5
• links(required): object links
  Target related links.
• name(required): string
  Blackout Name

  Example: my_blackout
• owner(required): string
  Owner of the blackout.

  Example: scott
• reason: string
  blackout reason

  Example: Network Outage
• status(required): string
  Allowed Values: [ "SCHEDULED", "START_PROCESSING", "START_PARTIAL", "START_FAILED", "STARTED", "STOP_PENDING", "STOP_FAILED", "STOP_PARTIAL", "EDIT_FAILED", "EDIT_PARTIAL", "EDIT_PENDING", "STOPPED", "ENDED", "END_PARTIAL" ]

  Blackout status.
• statusDisplayName: string
  Status display name in the cient locale.
• type(required): string
  Default Value: PATCHING

  Allowed Values: [ "PATCHING", "NOTIFICATION", "NOTIFICATION_MAINTENANCE" ]

  Type of the blackout.
• typeDisplayName: string
  Blackout type display name in the client locale

  Example: Benachrichtigungsblackout

{
    "x-em-sdk-level":"emSDK",
    "description":"This is the representation of the Blackout summary.",
    "type":"object",
    "required":[
        "id",
        "name",
        "type",
        "status",
        "links",
        "owner"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"Blackout ID",
            "example":"D91786E288D35455C3ADA1B329B49BB5"
        },
        "name":{
            "type":"string",
            "description":"Blackout Name",
            "example":"my_blackout"
        },
        "type":{
            "$ref":"#/components/schemas/BlackoutType"
        },
        "typeDisplayName":{
            "type":"string",
            "description":"Blackout type display name in the client locale",
            "example":"Benachrichtigungsblackout"
        },
        "reason":{
            "type":"string",
            "description":"blackout reason",
            "example":"Network Outage"
        },
        "status":{
            "$ref":"#/components/schemas/BlackoutStatus"
        },
        "statusDisplayName":{
            "type":"string",
            "description":"Status display name in the cient locale."
        },
        "owner":{
            "type":"string",
            "description":"Owner of the blackout.",
            "example":"scott"
        },
        "links":{
            "type":"object",
            "description":"Target related links.",
            "properties":{
                "self":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the blackout."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts/D91786E288D35455C3ADA1B329B49BB5"
                            }
                        }
                    ]
                },
                "targets":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the targets under blackout."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts/D91786E288DFSE2323ADA1B329B49BB5/targets"
                            }
                        }
                    ]
                }
            }
        }
    },
    "allOf":[
        {
            "$ref":"#/components/schemas/Schedule"
        }
    ]
}

Match All

This is the representation of the Blackout summary.

Show Source

• object Schedule
  Defining time schedule

{
    "x-em-sdk-level":"emSDK",
    "description":"This is the representation of the Blackout summary.",
    "type":"object",
    "required":[
        "id",
        "name",
        "type",
        "status",
        "links",
        "owner"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"Blackout ID",
            "example":"D91786E288D35455C3ADA1B329B49BB5"
        },
        "name":{
            "type":"string",
            "description":"Blackout Name",
            "example":"my_blackout"
        },
        "type":{
            "$ref":"#/components/schemas/BlackoutType"
        },
        "typeDisplayName":{
            "type":"string",
            "description":"Blackout type display name in the client locale",
            "example":"Benachrichtigungsblackout"
        },
        "reason":{
            "type":"string",
            "description":"blackout reason",
            "example":"Network Outage"
        },
        "status":{
            "$ref":"#/components/schemas/BlackoutStatus"
        },
        "statusDisplayName":{
            "type":"string",
            "description":"Status display name in the cient locale."
        },
        "owner":{
            "type":"string",
            "description":"Owner of the blackout.",
            "example":"scott"
        },
        "links":{
            "type":"object",
            "description":"Target related links.",
            "properties":{
                "self":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the blackout."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts/D91786E288D35455C3ADA1B329B49BB5"
                            }
                        }
                    ]
                },
                "targets":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Link"
                        },
                        {
                            "description":"Link to the targets under blackout."
                        },
                        {
                            "example":{
                                "href":"/em/api/blackouts/D91786E288DFSE2323ADA1B329B49BB5/targets"
                            }
                        }
                    ]
                }
            }
        }
    },
    "allOf":[
        {
            "$ref":"#/components/schemas/Schedule"
        }
    ]
}

Nested Schema : links

Type: object

Target related links.

Show Source

• self: self
• targets: targets

{
    "type":"object",
    "description":"Target related links.",
    "properties":{
        "self":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Link"
                },
                {
                    "description":"Link to the blackout."
                },
                {
                    "example":{
                        "href":"/em/api/blackouts/D91786E288D35455C3ADA1B329B49BB5"
                    }
                }
            ]
        },
        "targets":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Link"
                },
                {
                    "description":"Link to the targets under blackout."
                },
                {
                    "example":{
                        "href":"/em/api/blackouts/D91786E288DFSE2323ADA1B329B49BB5/targets"
                    }
                }
            ]
        }
    }
}

Nested Schema : Schedule

Type: object

Defining time schedule

Show Source

• isTargetZoneUsed: boolean
  To indicate the time should be interpreted in target's timezone or not. If Timezone is specified in time and useTargetZone is true, it will be reported as an ERROR condition

  Example: true
• recurring: string
  Frequency at which the operation must be executed repeatedly

  Example: Weekly
• scheduleType: string
  Currently we support ical specification default is ICAL, in future it can be extended to other types e.g CRON.
• startGracePeriodInMinutes: number
  Time in minutes after which the job will be marked as skipped if not started. Null or Negative value means no grace period.

  Example: 60
• timeToEnd: string
  end time for the job in the format YYYY-MM-DDTHH24:Mi:SSZTimezone Timezone specification is optional and will be defaulted to UTC.

  Example: 2021-03-02 22:00:13
• timeToStart: string
  start time for the job in the format YYYY-MM-DDTHH24:Mi:SSZTimezone Timezone specification is optional and will be defaulted to UTC.

  Example: 2021-03-01 21:23:03

{
    "description":"Defining time schedule",
    "type":"object",
    "properties":{
        "timeToStart":{
            "type":"string",
            "description":"start time for the job in the format YYYY-MM-DDTHH24:Mi:SSZTimezone Timezone specification is optional and will be defaulted to UTC.",
            "example":"2021-03-01 21:23:03"
        },
        "timeToEnd":{
            "type":"string",
            "description":"end time for the job in the format YYYY-MM-DDTHH24:Mi:SSZTimezone Timezone specification is optional and will be defaulted to UTC.",
            "example":"2021-03-02 22:00:13"
        },
        "isTargetZoneUsed":{
            "type":"boolean",
            "description":"To indicate the time should be interpreted in target's timezone or not. If Timezone is specified in time and useTargetZone is true, it will be reported as an ERROR condition",
            "example":true
        },
        "scheduleType":{
            "type":"string",
            "description":"Currently we support ical specification default is ICAL, in future it can be extended to other types e.g CRON."
        },
        "recurring":{
            "type":"string",
            "description":"Frequency at which the operation must be executed repeatedly",
            "example":"Weekly"
        },
        "startGracePeriodInMinutes":{
            "type":"number",
            "description":"Time in minutes after which the job will be marked as skipped if not started. Null or Negative value means no grace period.",
            "example":60
        }
    }
}

Nested Schema : self

Match All

Link to the blackout.

Show Source

• object Link
  It represents a Link
• Link to the blackout.
• Example: { "href":"/em/api/blackouts/D91786E288D35455C3ADA1B329B49BB5" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Link"
        },
        {
            "description":"Link to the blackout."
        },
        {
            "example":{
                "href":"/em/api/blackouts/D91786E288D35455C3ADA1B329B49BB5"
            }
        }
    ]
}

Nested Schema : targets

Match All

Link to the targets under blackout.

Show Source

• object Link
  It represents a Link
• Link to the targets under blackout.
• Example: { "href":"/em/api/blackouts/D91786E288DFSE2323ADA1B329B49BB5/targets" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Link"
        },
        {
            "description":"Link to the targets under blackout."
        },
        {
            "example":{
                "href":"/em/api/blackouts/D91786E288DFSE2323ADA1B329B49BB5/targets"
            }
        }
    ]
}

Nested Schema : Link

Type: object

It represents a Link

Show Source

• href: string
  URL for the link

{
    "type":"object",
    "properties":{
        "href":{
            "type":"string",
            "description":"URL for the link"
        }
    },
    "description":"It represents a Link"
}

Nested Schema : next

Match All

Link to the next page in the result set.

Show Source

• object Link
  It represents a Link
• Link to the next page in the result set.
• Example: { "href":"/em/api/blackouts?page=THE_NEXT_PAGE_TOKEN" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Link"
        },
        {
            "description":"Link to the next page in the result set."
        },
        {
            "example":{
                "href":"/em/api/blackouts?page=THE_NEXT_PAGE_TOKEN"
            }
        }
    ]
}

Nested Schema : previous

Match All

Link to the previous page in the result set.

Show Source

• object Link
  It represents a Link
• Link to the previous page in the result set.
• Example: { "href":"/em/api/blackouts?page=THE_PREVIOUS_PAGE_TOKEN" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Link"
        },
        {
            "description":"Link to the previous page in the result set."
        },
        {
            "example":{
                "href":"/em/api/blackouts?page=THE_PREVIOUS_PAGE_TOKEN"
            }
        }
    ]
}

Nested Schema : self

Match All

Link to the current page in the result set.

Show Source

• object Link
  It represents a Link
• Link to the current page in the result set.
• Example: { "href":"/em/api/blackouts?page=THIS_PAGE_TOKEN" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Link"
        },
        {
            "description":"Link to the current page in the result set."
        },
        {
            "example":{
                "href":"/em/api/blackouts?page=THIS_PAGE_TOKEN"
            }
        }
    ]
}

Examples

Select an example One notification blackout and one patching blackout No blackouts matching the criteria List called with limit of 2 but result set is bigger. This shows some middle page and not the first of last page

400 Response

in the case of illegal arguments like unsupported sort direction

Body ()

Root Schema : ErrorResponse

Type: object

Response sent back in the case of an Error

Show Source

• code(required): string
  The status code of the error
• message(required): string
  A descriptive error message

{
    "required":[
        "code",
        "message"
    ],
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"The status code of the error"
        },
        "message":{
            "type":"string",
            "description":"A descriptive error message"
        }
    },
    "description":"Response sent back in the case of an Error"
}

401 Response

client is not authenticated

Body ()

Root Schema : ErrorResponse

Type: object

Response sent back in the case of an Error

Show Source

• code(required): string
  The status code of the error
• message(required): string
  A descriptive error message

{
    "required":[
        "code",
        "message"
    ],
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"The status code of the error"
        },
        "message":{
            "type":"string",
            "description":"A descriptive error message"
        }
    },
    "description":"Response sent back in the case of an Error"
}

500 Response

internal error serving the request

Body ()

Root Schema : ErrorResponse

Type: object

Response sent back in the case of an Error

Show Source

• code(required): string
  The status code of the error
• message(required): string
  A descriptive error message

{
    "required":[
        "code",
        "message"
    ],
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"The status code of the error"
        },
        "message":{
            "type":"string",
            "description":"A descriptive error message"
        }
    },
    "description":"Response sent back in the case of an Error"
}

503 Response

indicates that a required service is not available.

Body ()

Root Schema : ErrorResponse

Type: object

Response sent back in the case of an Error

Show Source

• code(required): string
  The status code of the error
• message(required): string
  A descriptive error message

{
    "required":[
        "code",
        "message"
    ],
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"The status code of the error"
        },
        "message":{
            "type":"string",
            "description":"A descriptive error message"
        }
    },
    "description":"Response sent back in the case of an Error"
}

Back to Top