diff --git a/api/docs/openapi.yaml b/api/docs/openapi.yaml index 2ad9ab44..cb6e6438 100644 --- a/api/docs/openapi.yaml +++ b/api/docs/openapi.yaml @@ -1,18 +1,22 @@ openapi: 3.0.3 info: description: | - The API for [CronMon](https://github.com/cron-mon-io/cron-mon), which allows - you to create, modify, and delete Monitors, as well as start and finish Jobs - within those Monitors. + The API for [CronMon](https://github.com/cron-mon-io), which facilitates creating + and managing Monitors, API Keys and Alert Configurations, and using Monitors to + start and finish jobs. version: 0.1.0 title: CronMon API tags: - name: Monitors - description: "Operations on monitors" + description: Operations on monitors - name: Jobs - description: "Operations on Jobs" + description: Operations on Jobs - name: API Keys - description: "Operations on API Keys" + description: Operations on API Keys + - name: Alert Configurations + description: Operations on Alert Configurations + - name: Monitors x Alert Configurations + description: Operations on Monitors and Alert Configurations paths: /api/v1/monitors: @@ -46,12 +50,12 @@ paths: paging: total: 2 data: - - monitor_id: "cfe88463-5c04-4b43-b10f-1f508963cc5d" - name: "foo-backup.sh" + - monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: foo-backup.sh expected_duration: 1320 grace_duration: 300 last_started_job: - job_id: "c72be737-1089-4e10-9da3-0076f4d4123d" + job_id: c72be737-1089-4e10-9da3-0076f4d4123d start_time: "2024-03-31T20:54:00" end_time: null succeeded: null @@ -60,12 +64,12 @@ paths: late: false in_progress: true last_finished_job: null - - monitor_id: "e534a01a-4efe-4b8e-9b04-44a3c76b0462" - name: "analyse-bar.py" + - monitor_id: e534a01a-4efe-4b8e-9b04-44a3c76b0462 + name: analyse-bar.py expected_duration: 21600 grace_duration: 1800 last_started_job: - job_id: "68c71e5a-932f-4443-9b32-dd2e66381499" + job_id: 68c71e5a-932f-4443-9b32-dd2e66381499 start_time: "2024-03-31T12:35:00" end_time: "2024-03-31T12:59:00" succeeded: true @@ -74,7 +78,7 @@ paths: late: false in_progress: false last_finished_job: - job_id: "68c71e5a-932f-4443-9b32-dd2e66381499" + job_id: 68c71e5a-932f-4443-9b32-dd2e66381499 start_time: "2024-03-31T12:35:00" end_time: "2024-03-31T12:59:00" succeeded: true @@ -89,18 +93,18 @@ paths: post: tags: - Monitors - summary: "Create a new Monitor" + summary: Create a new Monitor security: - bearerAuth: [] requestBody: - description: "The new Monitor to create." + description: The new Monitor to create. required: true content: application/json: schema: $ref: "#/components/schemas/MonitorInfo" example: - name: "weekly-foobar" + name: weekly-foobar expected_duration: 43200 grace_duration: 7200 responses: @@ -112,8 +116,8 @@ paths: $ref: "#/components/schemas/Monitor" example: data: - monitor_id: "cfe88463-5c04-4b43-b10f-1f508963cc5d" - name: "weekly-foobar" + monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: weekly-foobar expected_duration: 43200 grace_duration: 7200 jobs: [] @@ -126,20 +130,20 @@ paths: get: tags: - Monitors - summary: "Retrieve a single Monitor" + summary: Retrieve a single Monitor security: - bearerAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor to retrieve." + description: The ID of the Monitor to retrieve. required: true schema: type: string format: uuid responses: "200": - description: "The retrieved Monitor." + description: The retrieved Monitor. content: application/json: schema: @@ -151,12 +155,12 @@ paths: $ref: "#/components/schemas/Monitor" example: data: - monitor_id: "cfe88463-5c04-4b43-b10f-1f508963cc5d" - name: "foo-backup.sh" + monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: foo-backup.sh expected_duration: 1320 grace_duration: 300 jobs: - - job_id: "c72be737-1089-4e10-9da3-0076f4d4123d" + - job_id: c72be737-1089-4e10-9da3-0076f4d4123d start_time: "2024-03-31T20:54:00" end_time: null succeeded: null @@ -164,7 +168,7 @@ paths: duration: null late: false in_progress: true - - job_id: "68c71e5a-932f-4443-9b32-dd2e66381499" + - job_id: 68c71e5a-932f-4443-9b32-dd2e66381499 start_time: "2024-03-31T12:35:00" end_time: "2024-03-31T12:59:00" succeeded: true @@ -181,31 +185,31 @@ paths: patch: tags: - Monitors - summary: "Modify a Monitor" + summary: Modify a Monitor security: - bearerAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor to retrieve." + description: The ID of the Monitor to retrieve. required: true schema: type: string format: uuid requestBody: - description: "The new Monitor information" + description: The new Monitor information required: true content: application/json: schema: $ref: "#/components/schemas/MonitorInfo" example: - name: "weekly-foobar" + name: weekly-foobar expected_duration: 43200 grace_duration: 7200 responses: "200": - description: "The retrieved Monitor." + description: The retrieved Monitor. content: application/json: schema: @@ -217,12 +221,12 @@ paths: $ref: "#/components/schemas/Monitor" example: data: - monitor_id: "cfe88463-5c04-4b43-b10f-1f508963cc5d" - name: "foo-backup.sh" + monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: foo-backup.sh expected_duration: 1320 grace_duration: 300 jobs: - - job_id: "c72be737-1089-4e10-9da3-0076f4d4123d" + - job_id: c72be737-1089-4e10-9da3-0076f4d4123d start_time: "2024-03-31T20:54:00" end_time: null succeeded: null @@ -230,7 +234,7 @@ paths: duration: null late: false in_progress: true - - job_id: "68c71e5a-932f-4443-9b32-dd2e66381499" + - job_id: 68c71e5a-932f-4443-9b32-dd2e66381499 start_time: "2024-03-31T12:35:00" end_time: "2024-03-31T12:59:00" succeeded: true @@ -247,20 +251,20 @@ paths: delete: tags: - Monitors - summary: "Delete a Monitor" + summary: Delete a Monitor security: - bearerAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor to retrieve." + description: The ID of the Monitor to delete. required: true schema: type: string format: uuid responses: "200": - description: "The Monitor was deleted." + description: The Monitor was deleted. "404": $ref: "#/components/responses/NotFoundError" "422": @@ -272,20 +276,20 @@ paths: post: tags: - Jobs - summary: "Start a Job within a Monitor" + summary: Start a Job within a Monitor security: - apiKeyAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor the Job belongs to." + description: The ID of the Monitor the Job belongs to. required: true schema: type: string format: uuid responses: "200": - description: "A job was started." + description: A job was started. content: application/json: schema: @@ -303,7 +307,7 @@ paths: format: uuid example: data: - job_id: "c72be737-1089-4e10-9da3-0076f4d4123d" + job_id: c72be737-1089-4e10-9da3-0076f4d4123d "404": $ref: "#/components/responses/NotFoundError" "422": @@ -315,27 +319,27 @@ paths: get: tags: - Jobs - summary: "Retrieve a single Job within a Monitor" + summary: Retrieve a single Job within a Monitor security: - bearerAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor the Job belongs to." + description: The ID of the Monitor the Job belongs to. required: true schema: type: string format: uuid - in: path name: job_id - description: "The ID of the Job to retrieve." + description: The ID of the Job to retrieve. required: true schema: type: string format: uuid responses: "200": - description: "The retrieved Job within the Monitor." + description: The retrieved Job within the Monitor. content: application/json: schema: @@ -347,7 +351,7 @@ paths: $ref: "#/components/schemas/Job" example: data: - job_id: "c72be737-1089-4e10-9da3-0076f4d4123d" + job_id: c72be737-1089-4e10-9da3-0076f4d4123d start_time: "2024-03-31T20:54:00" end_time: null succeeded: null @@ -366,26 +370,26 @@ paths: post: tags: - Jobs - summary: "Finish a Job within a Monitor" + summary: Finish a Job within a Monitor security: - apiKeyAuth: [] parameters: - in: path name: monitor_id - description: "The ID of the Monitor the Job belongs to." + description: The ID of the Monitor the Job belongs to. required: true schema: type: string format: uuid - in: path name: job_id - description: "The ID of the Job to retrieve." + description: The ID of the Job to retrieve. required: true schema: type: string format: uuid requestBody: - description: "Information about how the Job finished" + description: Information about how the Job finished required: true content: application/json: @@ -396,17 +400,17 @@ paths: properties: succeeded: type: boolean - description: "Whether or not the job finished successfully." + description: Whether or not the job finished successfully. output: type: string nullable: true - description: "Any output from the job" + description: Any output from the job example: succeeded: true - output: "Job finished" + output: Job finished responses: "200": - description: "Job finished successfully" + description: Job finished successfully content: application/json: schema: @@ -418,11 +422,11 @@ paths: $ref: "#/components/schemas/Job" example: data: - job_id: "68c71e5a-932f-4443-9b32-dd2e66381499" + job_id: 68c71e5a-932f-4443-9b32-dd2e66381499 start_time: "2024-03-31T12:35:00" end_time: "2024-03-31T12:59:00" succeeded: true - output: "Job finished" + output: Job finished duration: 1440 late: false in_progress: false @@ -466,20 +470,20 @@ paths: paging: total: 2 data: - - api_key_id: "773cade2-c6bd-4b3b-9974-46e412d54c25" - name: "My API Key" - masked: "crnmn_************tIn0" + - api_key_id: 773cade2-c6bd-4b3b-9974-46e412d54c25 + name: My API Key + masked: crnmn_************tIn0 last_used: time: "2024-03-31T20:54:00" - monitor_id: "cfe88463-5c04-4b43-b10f-1f508963cc5d" - monitor_name: "foo-backup.sh" - - api_key_id: "caf5389d-31ef-424a-bb65-cc3b50b62cee" - name: "My API Key" - masked: "crnmn_************tIn0" + monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + monitor_name: foo-backup.sh + - api_key_id: caf5389d-31ef-424a-bb65-cc3b50b62cee + name: My API Key + masked: crnmn_************tIn0 last_used: time: "2024-03-31T20:54:00" - monitor_id: "e534a01a-4efe-4b8e-9b04-44a3c76b0462" - monitor_name: "analyse-bar.py" + monitor_id: e534a01a-4efe-4b8e-9b04-44a3c76b0462 + monitor_name: analyse-bar.py "400": $ref: "#/components/responses/BadRequestError" "500": @@ -487,11 +491,11 @@ paths: post: tags: - API Keys - summary: "Create a new API Key" + summary: Create a new API Key security: - bearerAuth: [] requestBody: - description: "The new API Key to create." + description: The new API Key to create. required: true content: application/json: @@ -503,7 +507,7 @@ paths: name: type: string example: - name: "My API Key" + name: My API Key responses: "201": description: The newly created API Key @@ -523,7 +527,7 @@ paths: type: string example: data: - key: "crnmn_eyJpYXQiOjE3Mjk4OTI1NzQuMTk1NjUxLCJ1cmwiOiJodHRwczovL3NlbnRyeS5pbyIsInJlZ2lvbl91cmwiOiJodHRwczovL3VzLnNlbnRyeS5pbyIsIm9yZyI6InRhaWxzY29tIn0" + key: crnmn_eyJpYXQiOjE3Mjk4OTI1NzQuMTk1NjUxLCJ1cmwiOiJodHRwczovL3NlbnRyeS5pbyIsInJlZ2lvbl91cmwiOiJodHRwczovL3VzLnNlbnRyeS5pbyIsIm9yZyI6InRhaWxzY29tIn0 "400": $ref: "#/components/responses/BadRequestError" "500": @@ -533,20 +537,501 @@ paths: delete: tags: - API Keys - summary: "Delete/ revoke an API Key" + summary: Delete/ revoke an API Key security: - bearerAuth: [] parameters: - in: path name: api_key_id - description: "The ID of the API Key to delete." + description: The ID of the API Key to delete. required: true schema: type: string format: uuid responses: "200": - description: "The API Key was deleted." + description: The API Key was deleted. + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + + /api/v1/alert-configs: + get: + tags: + - Alert Configurations + summary: List alert configurations + description: Returns all alert configurations + security: + - bearerAuth: [] + responses: + "200": + description: A list of alert configurations. + content: + application/json: + schema: + type: object + required: + - data + - paging + properties: + data: + type: array + items: + $ref: "#/components/schemas/AlertConfigSummary" + paging: + $ref: "#/components/schemas/Paging" + example: + paging: + total: 2 + data: + - alert_config_id: 557360e7-277e-4821-bd56-e4137f35dcc0 + name: Slack alerts for lates + active: true + on_late: true + on_error: false + monitor_ids: + - cfe88463-5c04-4b43-b10f-1f508963cc5d + - e534a01a-4efe-4b8e-9b04-44a3c76b0462 + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + - alert_config_id: b1fd4478-46bd-4edd-adb2-5aa816784241 + name: Webhook alerts for errors + active: true + on_late: false + on_error: true + monitor_ids: + - cfe88463-5c04-4b43-b10f-1f508963cc5d + type: + webhook: + url: http://example.com/errors/callback + "400": + $ref: "#/components/responses/BadRequestError" + "500": + $ref: "#/components/responses/ServiceError" + post: + tags: + - Alert Configurations + summary: Createm a new alert configuration + security: + - bearerAuth: [] + requestBody: + description: The new alert configuration to create. + required: true + content: + application/json: + schema: + type: object + required: + - name + - active + - on_late + - on_error + - type + properties: + name: + type: string + description: The name to give the alert configuration + active: + type: boolean + description: Whether or not the alert configuration should be active + on_late: + type: boolean + description: | + Whether or not the configured alerts should be sent for jobs that are late + on_error: + type: boolean + description: | + Whether or not the configured alerts should be sent for jobs that exhibit an error + type: + type: object + description: The type alert being configured + oneOf: + - $ref: "#/components/schemas/SlackAlertConfig" + example: + name: Slack alerts + active: true + on_late: true + on_error: true + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + responses: + "201": + description: The newly created alert configuration + content: + application/json: + schema: + $ref: "#/components/schemas/AlertConfig" + example: + data: + alert_config_id: 8662e29c-65b8-4431-9fe3-3cea34d2b408 + name: Slack alerts + active: true + on_late: true + on_error: false + monitor_ids: [] + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + "400": + $ref: "#/components/responses/BadRequestError" + "500": + $ref: "#/components/responses/ServiceError" + + /api/v1/alert-configs/{alert_config_id}: + get: + tags: + - Alert Configurations + summary: Retrieve a specifc alert configuration + security: + - bearerAuth: [] + parameters: + - in: path + name: alert_config_id + description: The ID of the alert configuration to retrieve + required: true + schema: + type: string + format: uuid + responses: + "200": + description: The retrieved alert configuration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: "#/components/schemas/AlertConfig" + example: + data: + alert_config_id: 557360e7-277e-4821-bd56-e4137f35dcc0 + name: Slack alerts for lates + active: true + on_late: true + on_error: false + monitors: + - monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: backup-db.sh + - monitor_id: e534a01a-4efe-4b8e-9b04-44a3c76b0462 + name: generate-orders + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + "400": + $ref: "#/components/responses/BadRequestError" + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + patch: + tags: + - Alert Configurations + summary: Modify an alert configuration + description: | + Note this endpoint does not facilitate adding or remove the alert to a Monitor. This can be + done with `POST /api/v1/monitors/{monitor_id}/alert-configs` and + `DELETE /api/v1/monitors/{monitor_id}/alert-configs/{alert_config_id}`, respectively. + + This endpoint also does not allow for alert configurations to change type. If the `type` in the + request body is different to what the alert configuration is currently, a `400` is returned. + security: + - bearerAuth: [] + parameters: + - in: path + name: alert_config_id + description: The ID of the alert configuration to trigger a test alert for + required: true + schema: + type: string + format: uuid + requestBody: + description: The new alert configuration information. + required: true + content: + application/json: + schema: + type: object + required: + - name + - active + - on_late + - on_error + - type + properties: + name: + type: string + description: The name to give the alert configuration + active: + type: boolean + description: Whether or not the alert configuration should be active + on_late: + type: boolean + description: | + Whether or not the configured alerts should be sent for jobs that are late + on_error: + type: boolean + description: | + Whether or not the configured alerts should be sent for jobs that exhibit an error + type: + type: object + description: The type alert being configured + oneOf: + - $ref: "#/components/schemas/SlackAlertConfig" + example: + name: Slack alerts + active: true + on_late: true + on_error: true + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + responses: + "200": + description: The newly updated alert configuration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: "#/components/schemas/AlertConfig" + example: + data: + alert_config_id: 557360e7-277e-4821-bd56-e4137f35dcc0 + name: Slack alerts for lates + active: true + on_late: true + on_error: false + monitors: + - monitor_id: cfe88463-5c04-4b43-b10f-1f508963cc5d + name: backup-db.sh + - monitor_id: e534a01a-4efe-4b8e-9b04-44a3c76b0462 + name: generate-orders + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + "400": + $ref: "#/components/responses/BadRequestError" + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + delete: + tags: + - Alert Configurations + summary: Delete an alert configuration + security: + - bearerAuth: [] + parameters: + - in: path + name: alert_config_id + description: The ID of the alert configuration to delete. + required: true + schema: + type: string + format: uuid + responses: + "200": + description: The alert configuration was deleted. + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + + /api/v1/alert-configs/{alert_config_id}/test: + post: + tags: + - Alert Configurations + summary: Trigger a test alert + description: | + The contents of the alert depends on the alert type to a certain degree, but the message + within the alert will always contain "Test {name} Cron Mon alert, triggered by {email}", + where `name` is the name of the alert configuration, and `email` is the email address of + the authenticated user, obtained from the JWT in the `Authorization` header. + security: + - bearerAuth: [] + parameters: + - in: path + name: alert_config_id + description: The ID of the alert configuration to trigger a test alert for + required: true + schema: + type: string + format: uuid + responses: + "201": + description: The retrieved alert configuration. + "400": + $ref: "#/components/responses/BadRequestError" + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + + /api/v1/monitors/{monitor_id}/alert-configs: + get: + tags: + - Monitors x Alert Configurations + summary: List alert configurations used by a Monitor + security: + - bearerAuth: [] + parameters: + - in: path + name: monitor_id + description: The ID of the Monitor of which to retrieve alert configurations for + required: true + schema: + type: string + format: uuid + responses: + "200": + description: A list of alert configurations. + content: + application/json: + schema: + type: object + required: + - data + - paging + properties: + data: + type: array + items: + $ref: "#/components/schemas/AlertConfigSummary" + paging: + $ref: "#/components/schemas/Paging" + example: + paging: + total: 2 + data: + - alert_config_id: 557360e7-277e-4821-bd56-e4137f35dcc0 + name: Slack alerts for lates + active: true + on_late: true + on_error: false + monitor_ids: + - cfe88463-5c04-4b43-b10f-1f508963cc5d + - e534a01a-4efe-4b8e-9b04-44a3c76b0462 + type: + slack: + channel: "#cron-alerts" + token: a-slack-bot-oauth-token + - alert_config_id: b1fd4478-46bd-4edd-adb2-5aa816784241 + name: Webhook alerts for errors + active: true + on_late: false + on_error: true + monitor_ids: + - cfe88463-5c04-4b43-b10f-1f508963cc5d + type: + webhook: + url: http://example.com/errors/callback + "400": + $ref: "#/components/responses/BadRequestError" + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + post: + tags: + - Monitors x Alert Configurations + summary: Apply alert configurations to a Monitor + security: + - bearerAuth: [] + parameters: + - in: path + name: monitor_id + description: The ID of the Monitor to apply alert configurations to + required: true + schema: + type: string + format: uuid + requestBody: + description: The new alert configuration information. + required: true + content: + application/json: + schema: + type: object + required: + - alert_config_ids + properties: + alert_config_ids: + type: array + items: + type: string + format: uuid + description: The IDs of the alert configurations to apply to the Monitor + example: + alert_config_ids: + - be719a93-4b9c-496d-a8a2-ee2616d48db5 + - ac24ebd6-3b51-42c6-9156-777b63fce709 + - 509ea633-8ec8-4ec5-9ae0-6492a7d0b984 + responses: + "201": + description: The alert configurations were successfully applied to the Monitor. + "400": + $ref: "#/components/responses/BadRequestError" + "404": + $ref: "#/components/responses/NotFoundError" + "422": + $ref: "#/components/responses/UnprocessableEntityError" + "500": + $ref: "#/components/responses/ServiceError" + /api/v1/monitors/{monitor_id}/alert-configs/{alert_config_id}: + delete: + tags: + - Monitors x Alert Configurations + summary: Unapply an alert configuration from a Monitor + security: + - bearerAuth: [] + parameters: + - in: path + name: monitor_id + description: The ID of the Monitor for which the alert configuration will be unapplied + required: true + schema: + type: string + format: uuid + - in: path + name: alert_config_id + description: The ID of the alert configuration to unapply from the Monitor + required: true + schema: + type: string + format: uuid + responses: + "200": + description: The alert configuration was unapplied from the Monitor "404": $ref: "#/components/responses/NotFoundError" "422": @@ -557,7 +1042,7 @@ paths: components: responses: BadRequestError: - description: "The request could not be understood by the server due to malformed syntax." + description: The request could not be understood by the server due to malformed syntax. content: application/json: schema: @@ -570,10 +1055,10 @@ components: example: error: code: 400 - reason: "Bad request" - description: "The request could not be understood by the server due to malformed syntax." + reason: Bad request + description: The request could not be understood by the server due to malformed syntax. UnauthorizedError: - description: "The request requires user authentication." + description: The request requires user authentication. content: application/json: schema: @@ -586,10 +1071,10 @@ components: example: error: code: 401 - reason: "Unauthorized" - description: "The request requires user authentication." + reason: Unauthorized + description: The request requires user authentication. NotFoundError: - description: "The requested resource could not be found." + description: The requested resource could not be found. content: application/json: schema: @@ -602,10 +1087,10 @@ components: example: error: code: 404 - reason: "Not Found" - description: "The requested resource could not be found." + reason: Not Found + description: The requested resource could not be found. UnprocessableEntityError: - description: "The request was well-formed but was unable to be followed due to semantic errors." + description: The request was well-formed but was unable to be followed due to semantic errors. content: application/json: schema: @@ -618,10 +1103,10 @@ components: example: error: code: 422 - reason: "nprocessable Entity" - description: "The request was well-formed but was unable to be followed due to semantic errors." + reason: Unprocessable Entity + description: The request was well-formed but was unable to be followed due to semantic errors. ServiceError: - description: "The server encountered an internal error while processing this request." + description: The server encountered an internal error while processing this request. content: application/json: schema: @@ -629,8 +1114,8 @@ components: example: error: code: 500 - reason: "Internal Server Error" - description: "The server encountered an internal error while processing this request." + reason: Internal Server Error + description: The server encountered an internal error while processing this request. schemas: Monitor: description: A cronjob monitor @@ -762,7 +1247,7 @@ components: type: boolean description: Whether or not the job is in progress. MonitorInfo: - description: "Information required to create and modify Monitors" + description: Information required to create and modify Monitors type: object required: - name @@ -770,20 +1255,20 @@ components: - grace_duration properties: name: - description: "The name of the Monitor" + description: The name of the Monitor type: string expected_duration: - description: "The expected duration of the monitored job, in seconds" + description: The expected duration of the monitored job, in seconds type: integer format: int32 minimum: 0 grace_duration: - description: "The numbers of seconds of grace to give to the jobs duration" + description: The numbers of seconds of grace to give to the jobs duration type: integer format: int32 minimum: 0 ApiKey: - description: "An API key" + description: An API key type: object required: - api_key_id @@ -826,8 +1311,109 @@ components: monitor_name: type: string description: The name of the Monitor that was accessed + AlertConfig: + description: A configuration for an alert + type: object + required: + - alert_config_id + - name + - active + - on_late + - on_error + - monitors + - type + properties: + alert_config_id: + type: string + format: uuid + description: The unique identifier for the alert configuration + name: + type: string + description: The name of the alert configuration + active: + type: boolean + description: | + Whether or not the alert configuration is active. Alert configurations will never trigger alerts + whilst they are inactive. + on_late: + type: boolean + description: Whether or not the configured alerts should be sent for jobs that are late + on_error: + type: boolean + description: Whether or not the configured alerts should be sent for jobs that exhibit an error + monitors: + type: array + items: + type: object + required: + - monitor_id + - name + properties: + monitor_id: + type: string + format: uuid + description: The ID of a Monitor that is currently using this alert configuration + name: + type: string + description: The name of a Monitor that is currently using this alert configuration + description: Monitors that are using this alert configuration + type: + type: object + oneOf: + - $ref: "#/components/schemas/SlackAlertConfig" + SlackAlertConfig: + description: Slack-specific alert configuration + type: object + required: + - slack + properties: + slack: + type: object + required: + - channel + - token + properties: + channel: + type: string + description: The channel to send the Slack alerts to + token: + type: string + description: The Slack Bot OAuth token to use to send the Slack alert (via chat.postMessage) + AlertConfigSummary: + description: A configuration for an alert + type: object + required: + - alert_config_id + - name + - active + - on_late + - on_error + - type + properties: + alert_config_id: + type: string + format: uuid + description: The unique identifier for the alert configuration + name: + type: string + description: The name of the alert configuration + active: + type: boolean + description: | + Whether or not the alert configuration is active. Alert configurations will never trigger alerts + whilst they are inactive. + on_late: + type: boolean + description: Whether or not the configured alerts should be sent for jobs that are late + on_error: + type: boolean + description: Whether or not the configured alerts should be sent for jobs that exhibit an error + type: + type: string + enum: + - slack Paging: - description: "Pagination information" + description: Pagination information type: object required: - total @@ -838,7 +1424,7 @@ components: minimum: 0 description: The total number of entities in the response. Error: - description: "An error response" + description: An error response type: object required: - error @@ -846,7 +1432,7 @@ components: error: $ref: "#/components/schemas/ErrorInfo" ErrorInfo: - description: "Information about an error" + description: Information about an error type: object required: - code