Jump to

• Request
• Response

List blackouts

get

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

This API returns a list of blackouts based on 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

Show Source

• object Schedule
  Schedule details

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

Schedule details

Show Source

• isTargetZone: boolean
  To indicate if the time should be interpreted in the target timezone or not. If timezone is specified in time and isTargetZone is true, it will be reported as an ERROR condition
• recurring: string
  Frequency at which the operation must be executed repeatedly

  Example: frequency:weekly;days:2,
• scheduleType: string
  Currently we support ICAL specification default is ICAL, in the future it can be extended to other types e.g CRON.
• startGracePeriodInMinutes: integer
  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 (date-time)
  End time
• timeToStart: string (date-time)
  Start time

{
    "description":"Schedule details",
    "type":"object",
    "properties":{
        "timeToStart":{
            "type":"string",
            "description":"Start time",
            "format":"date-time"
        },
        "timeToEnd":{
            "type":"string",
            "description":"End time",
            "format":"date-time"
        },
        "isTargetZone":{
            "type":"boolean",
            "description":"To indicate if the time should be interpreted in the target timezone or not. If timezone is specified in time and isTargetZone is true, it will be reported as an ERROR condition"
        },
        "scheduleType":{
            "type":"string",
            "description":"Currently we support ICAL specification default is ICAL, in the 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":"frequency:weekly;days:2,"
        },
        "startGracePeriodInMinutes":{
            "type":"integer",
            "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

Show Source

• object Link
  Represents a link(could be self, previous or next)
• 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

Show Source

• object Link
  Represents a link(could be self, previous or next)
• 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

Represents a link(could be self, previous or next)

Show Source

• href: string
  URL for Link

  Example: /em/api/<resources>?page=b2Zmc2V0OjA&limit=0

{
    "type":"object",
    "description":"Represents a link(could be self, previous or next)",
    "properties":{
        "href":{
            "type":"string",
            "description":"URL for Link",
            "example":"/em/api/<resources>?page=b2Zmc2V0OjA&limit=0"
        }
    }
}

Nested Schema : next

Match All

Show Source

• object Link
  Represents a link(could be self, previous or next)
• 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

Show Source

• object Link
  Represents a link(could be self, previous or next)
• 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

Show Source

• object Link
  Represents a link(could be self, previous or next)
• 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

Error response

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing
• message(required): string
  A human-readable error string

{
    "description":"Error response",
    "type":"object",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string",
            "type":"string"
        }
    }
}

401 Response

client is not authenticated

Body ()

Root Schema : ErrorResponse

Type: object

Error response

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing
• message(required): string
  A human-readable error string

{
    "description":"Error response",
    "type":"object",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string",
            "type":"string"
        }
    }
}

500 Response

internal error serving the request

Body ()

Root Schema : ErrorResponse

Type: object

Error response

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing
• message(required): string
  A human-readable error string

{
    "description":"Error response",
    "type":"object",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string",
            "type":"string"
        }
    }
}

503 Response

indicates that a required service is not available.

Body ()

Root Schema : ErrorResponse

Type: object

Error response

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing
• message(required): string
  A human-readable error string

{
    "description":"Error response",
    "type":"object",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string",
            "type":"string"
        }
    }
}

Back to Top