openapi: 3.0.1 info: title: Alerting API description: 'This is a simple API for a dynamic, reactive alerting system (minus the notification component).' version: 0.0.1 servers: - url: http://localhost:8080/api/alerting/v1 tags: - name: Alerts - name: Recipients security: - alerting_auth: - read - write paths: /accounts/{account_id}/alerts: get: tags: - Alerts description: Get the list of alerts for an account summary: Get the list of alerts for an account operationId: getListOfAlerts parameters: - name: account_id in: path description: ID of the account to get alerts from. required: true schema: type: integer format: int64 example: 1234567 - name: include_recipients in: query description: > If set to true, then the list of all recipients belonging to each alert will be included in the response. schema: type: boolean default: false example: true responses: 200: description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Alert' example: - id: "percentageOfDeliveryFailures" name: "Percentage of Delivery Failures" threshold: "90" type: "PERCENTAGE_OF_DELIVERY_FAILURES" frequency: "15m" enabled: true last_triggered: "2021-04-22T16:33:21.959Z" notification_sent: "2021-04-22T16:33:21.959Z" is_triggered: true, reference_time_period: "1 Week" created: "2021-04-22T16:33:21.959Z" updated: "2021-04-22T16:33:21.959Z" updated_by: "someOtherUser" recipients: - id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" created: "2021-02-22T16:09:28.139Z" updated: "2021-04-26T04:01:13.448Z" updated_by: "someUser" - id: "someOtherUsersEmail" recipient: "someOtherUser@somedomain.com" type: "EMAIL" created: "2021-03-04T07:17:33.244Z" updated: "2021-03-04T08:00:54.562Z" updated_by: "someOtherUser" - id: "failureThresholdAlert" name: "Too Many Errors" threshold: "1820" type: "FAILURE_THRESHOLD_ALERT" frequency: "5m" enabled: false last_triggered: "2021-04-22T16:33:21.959Z" notification_sent: "2021-04-22T16:33:21.959Z" is_triggered: true reference_time_period: "1 Month" created: "2021-04-22T16:33:21.959Z" updated: "2021-04-26T04:01:13.448Z" updated_by: "someOtherUser" recipients: - id: "someUserHttpRecipient" recipient: "https://some.test.callback.com/callback" type: "HTTP" username: "mikeRoweSoft" password: "iSuPpOrTwInDoWs" created: "2021-05-19T02:39:12.922Z" updated: "2021-05-19T02:39:12.922Z" updated_by: "someUser" 403: $ref: '#/components/responses/Forbidden' security: - alerting_auth: - write:alert - read:alert post: tags: - Alerts description: Add an alert to the specified account. summary: Add an alert to the specified account operationId: addAlert parameters: - name: account_id in: path description: ID of an account to add an alert to. required: true schema: type: integer format: int64 example: 1234567 requestBody: content: application/json: schema: properties: id: type: string description: > External ID used by users to refer to alert. If an ID is specified, the ID must be account-unique. If not provided, it will be automatically generated. name: type: string description: The name of this alert default: "Default value differs by the alert type" threshold: type: string description: A threshold must be given for a custom alert. default: "Default value differs by the alert type" type: type: string description: The type of alert being added to the account enum: - PERCENTAGE_OF_DELIVERY_FAILURES - FAILURE_THRESHOLD_ALERT - HARD_CODED_ALERT_1 - HARD_CODED_ALERT_2 frequency: type: string description: The frequency of how often the alerting condition is checked. default: "15m" enabled: type: boolean description: Boolean value denoting whether the alert is enabled or not. default: true reference_time_period: type: string description: Time period to run the alerting condition against (lags in time series data). default: "1 Month" example: id: "testAlert1" name: "Too Many Messages Are Being Sent" threshold: "666" type: "FAILURE_THRESHOLD_ALERT" frequency: "5m" enabled: false reference_time_period: "1 Week" required: - type responses: 201: description: Successfully created new alert content: application/json: schema: $ref: '#/components/schemas/Alert' example: id: "testAlert1" name: "Too Many Messages Are Being Sent" threshold: "666" type: "FAILURE_THRESHOLD_ALERT" frequency: "15m" enabled: false reference_time_period: "1 Week" created: "2021-04-22T16:33:21.959Z" updated: "2021-04-22T16:33:21.959Z" updated_by: "someUser" 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 409: description: An alert with the specified ID already exists on the given account 422: description: > * Invalid alert request * The type was unspecified, or does not exist security: - alerting_auth: - write:alert - read:alert /accounts/{account_id}/alerts/{alert_id}: get: tags: - Alerts description: Get an alert given an alert ID and account ID. summary: Get an alert given an alert ID and account ID operationId: getAlertById parameters: - name: account_id in: path description: ID of the account to get alerts from. required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: External ID used by users to refer to an alert. required: true schema: type: string example: "someHardcodedAlert" - name: include_recipients in: query description: > If set to true, then the list of all recipients belonging to the alert will be included in the response. schema: type: boolean default: false example: true responses: 200: description: Found alert content: application/json: schema: $ref: '#/components/schemas/Alert' example: id: "someHardcodedAlert" name: "Percentage of Delivery Failures" threshold: "90" type: "PERCENTAGE_OF_DELIVERY_FAILURES" frequency: "15m" enabled: true last_triggered: "2021-04-22T16:33:21.959Z" notification_sent: "2021-04-22T16:33:21.959Z" is_triggered: true reference_time_period: "1 Week" created: "2021-04-22T16:33:21.959Z" updated: "2021-04-22T16:33:21.959Z" updated_by: "someOtherUser" 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFoundAlert' security: - alerting_auth: - write:alerts - read:alerts patch: tags: - Alerts description: > Update the attributes of an existing alert. Note that if a user attempts to update the type of an alert, the value will be ignored. summary: Update the attributes of an existing alert operationId: updateAlert parameters: - name: account_id in: path description: > ID of the account that the alert belongs to. This cannot be updated and will be ignored if placed in the payload required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: External ID used by users to refer to an alert. This cannot be updated and will be ignored if placed in the payload required: true schema: type: string example: "testAlert1" requestBody: content: application/json: schema: properties: name: type: string description: A new name for the specified alert threshold: type: string description: A new threshold for the alert frequency: type: string description: The frequency of how often the alerting condition is checked enabled: type: boolean description: Boolean value denoting whether the alert is enabled or not reference_time_period: type: string description: Time period to run the alerting condition against (lags in time series data) example: name: "Too Many Messages Are Being Sent" threshold: "955" frequency: "15m" enabled: true reference_time_period: "1 Month" responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/Alert' example: id: "testAlert1" name: "Too Many Messages Are Being Sent" threshold: "955" type: "FAILURE_THRESHOLD_ALERT" frequency: "15m" enabled: true last_triggered: "2021-04-22T16:33:21.959Z" notification_sent: "2021-04-22T16:33:21.959Z" is_triggered: false reference_time_period: "1 Month" created: "2021-04-22T16:33:21.959Z" updated: "2021-05-19T12:45:09.127Z" updated_by: "someUser" 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFoundAlert' 422: description: > * Invalid update request * User was attempting to update alert type * User attempted to update name value to an empty value * User attempted to update threshold value to empty value security: - alerting_auth: - write:alerts - read:alerts delete: tags: - Alerts description: > Remove the specified alert from the account. When an alert is deleted, all recipients belonging to the alert are also removed. summary: Remove the specified alert from the account operationId: deleteAlert parameters: - name: account_id in: path description: ID of the account that the alert exists on. required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: External ID used by users to refer to an alert. required: true schema: type: string example: "testAlert1" responses: 204: description: Successfully deleted alert 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFoundAlert' security: - alerting_auth: - write:alert - read:alert /accounts/{account_id}/recipients: get: tags: - Recipients description: Get the list of all recipients on the specified account summary: Get the list of all recipients on the specified account operationId: getAllRecipients parameters: - name: account_id in: path description: ID of the account to get recipients from required: true schema: type: integer format: int64 example: 1234567 responses: 200: description: Successfully returned the list of recipients content: application/json: schema: type: array items: $ref: '#/components/schemas/Recipient' example: - id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" created: "2021-02-22T16:09:28.139Z" updated: "2021-04-26T04:01:13.448Z" updated_by: "someUser" - id: "someOtherUsersEmail" recipient: "someOtherUser@somedomain.com" type: "EMAIL" created: "2021-03-04T07:17:33.244Z" updated: "2021-03-04T08:00:54.562Z" updated_by: "someOtherUser" - id: "someUserHttpRecipient" recipient: "https://some.test.callback.com/callback" type: "HTTP" username: "mikeRoweSoft" password: "iSuPpOrTwInDoWs" created: "2021-05-19T02:39:12.922Z" updated: "2021-05-19T02:39:12.922Z" updated_by: "someUser" 403: $ref: '#/components/responses/Forbidden' security: - alerting_auth: - write:alerts - read:alerts /accounts/{account_id}/alerts/{alert_id}/recipients: get: tags: - Recipients description: Get the list of recipients for an alert summary: Get the list of recipients for an alert operationId: getRecipientList parameters: - name: account_id in: path description: ID of the account to get recipients from required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: The alert that the recipients belong to required: true schema: type: string example: "percentageOfDeliveryFailures" responses: 200: description: Successfully returned list of recipients content: application/json: schema: type: array items: $ref: '#/components/schemas/Recipient' example: - id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" created: "2021-02-22T16:09:28.139Z" updated: "2021-04-26T04:01:13.448Z" updated_by: "someUser" - id: "someOtherUsersEmail" recipient: "someOtherUser@somedomain.com" type: "EMAIL" created: "2021-03-04T07:17:33.244Z" updated: "2021-03-04T08:00:54.562Z" updated_by: "someOtherUser" 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFoundAlert' security: - alerting_auth: - write:alerts - read:alerts post: tags: - Recipients description: Add one or more recipients to an alert. Note that no more than 25 recipients can be added to an alert. summary: Add one or more recipients to an alert operationId: addRecipient parameters: - name: account_id in: path description: ID of the account that the recipient exists on. required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: The alert that the recipient(s) will belong to required: true schema: type: string example: "percentageOfDeliveryFailures" requestBody: content: application/json: schema: type: array items: type: object properties: id: type: string description: > External ID used by users to refer to a recipient. This must be unique among all recipient IDs given for the specified account. If this field is not provided, an ID is generated. recipient: type: string description: > Identifier that indicates who is receiving the notification. * When the type is SMS, the recipient value must conform to the E.164 format recommendation * When the type is EMAIL, the recipient value must conform to RFC-5322 * When the type is HTTP, as of RFC 3986, URIs should no longer support credentials. As a result, all URIs must conform to “http[s]://host[:port]/path?querystring” format. type: type: string enum: - EMAIL - SMS - HTTP description: The type of the recipient. username: type: string description: > Username for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. password: type: string description: > Password for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. required: - recipient - type example: - id: "someUserHttpRecipient" recipient: "https://some.test.callback.com/callback" type: "HTTP" username: "mikeRoweSoft" password: "iSuPpOrTwInDoWs" - id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" responses: 201: description: Successfully created new recipient(s) content: application/json: schema: type: array items: $ref: '#/components/schemas/Recipient' example: - id: "someUserHttpRecipient" recipient: "https://some.test.callback.com/callback" type: "HTTP" username: "mikeRoweSoft" password: "iSuPpOrTwInDoWs" created: "2021-05-19T02:39:12.922Z" updated: "2021-05-19T02:39:12.922Z" updated_by: "someUser" - id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" created: "2021-02-22T16:09:28.139Z" updated: "2021-02-22T16:09:28.139Z" updated_by: "someUser" 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: $ref: '#/components/responses/NotFoundAlert' 409: description: A recipient with the specified ID already exists on the given account 422: description: > * Invalid recipient request * User provided an unsupported type for one or more of the recipients * User attempted to add more than 25 recipients to the alert * Alert already has the maximum number of recipients security: - alerting_auth: - write:alerts - read:alerts /accounts/{account_id}/alerts/{alert_id}/recipients/{recipient_id}: get: tags: - Recipients description: Get a recipient given the account ID, alert ID, and recipient ID. summary: Get a recipient given the account ID, alert ID, and recipient ID operationId: getRecipient parameters: - name: account_id in: path description: ID of the account to get recipients from required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: The alert that the recipient belongs to required: true schema: type: string example: "someHardCodedAlert" - name: recipient_id in: path description: External ID used by users to refer to a recipient required: true schema: type: string example: "someUsersEmail" responses: 200: description: Found Recipient content: application/json: schema: $ref: '#/components/schemas/Recipient' example: id: "someUsersEmail" recipient: "someUser@somedomain.com" type: "EMAIL" created: "2021-02-22T16:09:28.139Z" updated: "2021-04-26T04:01:13.448Z" updated_by: "someUser" 403: $ref: '#/components/responses/Forbidden' 404: description: > * Recipient ID is unknown * Alert ID is unknown security: - alerting_auth: - write:alerts - read:alerts patch: tags: - Recipients description: Update the attributes of a recipient. summary: Update the attributes of a recipient operationId: updateRecipient parameters: - name: account_id in: path description: ID of the account that the recipient exists on. required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: The alert that the recipient belongs to required: true schema: type: string example: "someHardCodedAlert" - name: recipient_id in: path description: External ID used by users to refer to a recipient required: true schema: type: string example: "someUserHttpRecipient" requestBody: content: application/json: schema: type: object properties: recipient: type: string description: > Identifier that indicates who is receiving the notification. * When the type is SMS, the recipient value must conform to the E.164 format recommendation * When the type is EMAIL, the recipient value must conform to RFC-5322 * When the type is HTTP, as of RFC 3986, URIs should no longer support credentials. As a result, all URIs must conform to “http[s]://host[:port]/path?querystring” format. type: type: string enum: - EMAIL - SMS - HTTP description: The type of the recipient username: type: string description: > Username for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. password: type: string description: > Password for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. example: password: "AppleHQLooksLikeAHalo.Suspicious!" responses: 200: description: Successfully updated recipient content: application/json: schema: $ref: '#/components/schemas/Recipient' example: id: "someUserHttpRecipient" recipient: "https://some.test.callback.com/callback" type: "HTTP" username: "mikeRoweSoft" password: "AppleHQLooksLikeAHalo.Suspicious!" created: "2021-05-19T02:39:12.922Z" updated: "2021-05-19T03:13:59.164Z" updated_by: "someUser" 400: $ref: '#/components/responses/BadRequest' 403: $ref: '#/components/responses/Forbidden' 404: description: > * Recipient ID is unknown * Alert ID is unknown 422: description: > * Invalid update recipient request * Invalid type provided * Invalid or unsupported recipient URI given security: - alerting_auth: - write:alerts - read:alerts delete: tags: - Recipients description: Delete a recipient. summary: Delete a recipient operationId: deleteRecipient parameters: - name: account_id in: path description: ID of the account that the recipient exists on required: true schema: type: integer format: int64 example: 1234567 - name: alert_id in: path description: The alert that the recipient(s) belong to required: true schema: type: string example: "someHardCodedAlert" - name: recipient_id in: path description: > External ID used by users to refer to a recipient. Multiple recipients can be deleted by specify a comma-separated list of recipient ID's. required: true schema: type: string example: "someUserHttpRecipient,someUsersEmail" responses: 204: description: Successfully removed recipient(s) 403: $ref: '#/components/responses/Forbidden' 404: description: > * One or more recipient IDs are unknown * Alert ID is unknown security: - alerting_auth: - write:alerts - read:alerts components: responses: Forbidden: description: > * Unknown Account * User is not allowed to represent the given account BadRequest: description: Request is invalid NotFoundAlert: description: Alert ID is unknown schemas: Alert: type: object properties: id: type: string description: Hardcoded or account-unique identifier for the alert name: type: string description: The name of this alert threshold: type: string description: The threshold value associated with this alert type: type: string description: The type of alert. The type will be an enum value matching one of the hard coded alerts. enum: - PERCENTAGE_OF_DELIVERY_FAILURES - FAILURE_THRESHOLD_ALERT - HARD_CODED_ALERT_1 - HARD_CODED_ALERT_2 frequency: type: string description: The frequency of how often the alerting condition is checked enabled: type: boolean description: Boolean value denoting whether the alert is enabled or not last_triggered: type: string description: > Timestamp of when the alert was last triggered, conforming to RFC 3339 format. The time zone is always UTC notification_sent: type: string description: > Timestamp of when the last notification was sent, conforming to RFC 3339 format. The time zone is always UTC is_triggered: type: boolean description: Boolean value denoting whether the alert is still currently being triggered reference_time_period: type: string description: Time period to run the alerting condition against (lags in time series data) created: type: string description: > Timestamp of when the alert was created, conforming to RFC 3339 format. The time zone is always UTC. For the create operation, the updated time will be the same as the created time. updated: type: string description: > Timestamp of when the alert was last updated, conforming to RFC 3339 format. The time zone is always UTC updated_by: type: string description: The last user to update the alert recipients: type: array description: > The list of full recipient objects is only returned when the include_recipients parameter is set to true items: $ref: '#/components/schemas/Recipient' Recipient: type: object properties: id: type: string description: Account-unique identifier for the recipient recipient: type: string description: Identifier that indicates who is receiving the notification type: type: string enum: - EMAIL - SMS - HTTP description: Type of recipient. username: type: string description: > Username for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. password: type: string description: > Password for recipient HTTP webhook authentication. Only applicable to HTTP recipient types. created: type: string description: > Timestamp of when the recipient was created, conforming to RFC 3339 format. The time zone is always UTC. updated: type: string description: > Timestamp of when the recipient was last updated, conforming to RFC 3339 format. The time zone is always UTC. For the create operation, the updated time will be the same as the created time. updated_by: type: string description: The last user to update the recipient. securitySchemes: alerting_auth: type: oauth2 flows: authorizationCode: authorizationUrl: https://login.alexjclarke.com/oauth/authorize tokenUrl: https://login.alexjclarke.com/oauth/token scopes: read:alerts: read your alerts write:alerts: modify alerts in your account