From b182aa2ceb8950c340b8d5a06f2c34551e0e110b Mon Sep 17 00:00:00 2001 From: dborovcanin Date: Mon, 6 Apr 2026 20:29:04 +0000 Subject: [PATCH] deploy: 94255e239330385e9a7b7ce838205edf1a13901b --- .nojekyll | 0 CNAME | 1 + alarms.yaml | 508 ++++++++++++++++++++++++++++ bootstrap.yaml | 699 +++++++++++++++++++++++++++++++++++++++ index.html | 181 ++++++++++ notifiers.yaml | 292 ++++++++++++++++ readers.yaml | 312 +++++++++++++++++ reports.yaml | 556 +++++++++++++++++++++++++++++++ rules.yaml | 586 ++++++++++++++++++++++++++++++++ schemas/health_info.yaml | 30 ++ 10 files changed, 3165 insertions(+) create mode 100644 .nojekyll create mode 100644 CNAME create mode 100644 alarms.yaml create mode 100644 bootstrap.yaml create mode 100644 index.html create mode 100644 notifiers.yaml create mode 100644 readers.yaml create mode 100644 reports.yaml create mode 100644 rules.yaml create mode 100644 schemas/health_info.yaml diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/CNAME b/CNAME new file mode 100644 index 000000000..25fde4ce0 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +docs.api.magistrala.absmach.eu diff --git a/alarms.yaml b/alarms.yaml new file mode 100644 index 000000000..b7d833b38 --- /dev/null +++ b/alarms.yaml @@ -0,0 +1,508 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala Alarms API + description: | + HTTP API for managing alarms service. + Some useful links: + - [The Magistrala repository](https://github.com/absmach/magistrala) + contact: + email: info@absmach.eu + license: + name: Apache 2.0 + url: https://github.com/absmach/magistrala/blob/main/LICENSE + version: 0.18.5 + +servers: + - url: http://localhost:8050 + - url: https://localhost:8050 + +tags: + - name: alarms + description: Everything about your Alarms + externalDocs: + description: Find out more about alarms + url: https://docs.magistrala.absmach.eu + +paths: + /{domainID}/alarms: + get: + operationId: listAlarms + summary: List Alarms + description: | + Retrieves a list of alarms with optional filtering + tags: + - alarms + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Order' + - $ref: '#/components/parameters/Dir' + - $ref: '#/components/parameters/ChannelID' + - $ref: '#/components/parameters/ClientID' + - $ref: '#/components/parameters/Subtopic' + - $ref: '#/components/parameters/RuleID' + - $ref: '#/components/parameters/Status' + - $ref: '#/components/parameters/AssigneeID' + - $ref: '#/components/parameters/Severity' + - $ref: '#/components/parameters/UpdatedBy' + - $ref: '#/components/parameters/AssignedBy' + - $ref: '#/components/parameters/AcknowledgedBy' + - $ref: '#/components/parameters/ResolvedBy' + - $ref: '#/components/parameters/CreatedFrom' + - $ref: '#/components/parameters/CreatedTo' + security: + - bearerAuth: [] + responses: + '200': + $ref: '#/components/responses/AlarmsPageRes' + '400': + description: Failed due to malformed query parameters + '401': + description: Missing or invalid access token + '422': + description: Database can't process request + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/alarms/{alarmID}: + get: + operationId: viewAlarm + summary: View Alarm + description: Retrieves an alarm by ID + tags: + - alarms + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/AlarmID' + security: + - bearerAuth: [] + responses: + '200': + $ref: '#/components/responses/AlarmRes' + '400': + description: Missing or invalid alarm ID + '401': + description: Missing or invalid access token + '403': + description: Failed to perform authorization over the entity + '404': + description: Alarm does not exist + '422': + description: Database can't process request + '500': + $ref: '#/components/responses/ServiceError' + put: + operationId: updateAlarm + summary: Update Alarm + description: Updates an existing alarm + tags: + - alarms + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/AlarmID' + security: + - bearerAuth: [] + requestBody: + $ref: '#/components/requestBodies/AlarmUpdateReq' + responses: + '200': + $ref: '#/components/responses/AlarmRes' + '400': + description: Failed due to malformed JSON + '401': + description: Missing or invalid access token + '403': + description: Failed to perform authorization over the entity + '404': + description: Alarm does not exist + '415': + description: Missing or invalid content type + '422': + description: Database can't process request + '500': + $ref: '#/components/responses/ServiceError' + delete: + operationId: deleteAlarm + summary: Delete Alarm + description: Deletes an alarm + tags: + - alarms + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/AlarmID' + security: + - bearerAuth: [] + responses: + '204': + description: Alarm deleted successfully + '400': + description: Failed due to malformed alarm ID + '401': + description: Missing or invalid access token + '403': + description: Failed to perform authorization over the entity + '404': + description: Alarm does not exist + '422': + description: Database can't process request + '500': + $ref: '#/components/responses/ServiceError' + + /health: + get: + summary: Retrieves service health check info + tags: + - health + security: [] + responses: + '200': + $ref: '#/components/responses/HealthRes' + '500': + $ref: '#/components/responses/ServiceError' + +components: + schemas: + Alarm: + type: object + properties: + id: + type: string + description: Unique alarm identifier + readOnly: true + rule_id: + type: string + description: Rule ID that triggered this alarm + domain_id: + type: string + description: Domain ID this alarm belongs to + channel_id: + type: string + description: Channel ID where the alarm was triggered + client_id: + type: string + description: Client ID that triggered the alarm + subtopic: + type: string + description: Subtopic associated with the alarm + status: + type: string + description: Alarm status + enum: [active, cleared] + measurement: + type: string + description: Measurement that triggered the alarm + value: + type: string + description: Value that triggered the alarm + unit: + type: string + description: Unit of measurement + threshold: + type: string + description: Threshold value that was exceeded + cause: + type: string + description: Cause or description of the alarm + severity: + type: integer + description: Severity level (0-100) + minimum: 0 + maximum: 100 + assignee_id: + type: string + description: ID of the user assigned to this alarm + created_at: + type: string + format: date-time + description: Creation timestamp + readOnly: true + updated_at: + type: string + format: date-time + description: Last update timestamp + readOnly: true + updated_by: + type: string + description: User who last updated the alarm + readOnly: true + assigned_at: + type: string + format: date-time + description: When the alarm was assigned + readOnly: true + assigned_by: + type: string + description: User who assigned the alarm + readOnly: true + acknowledged_at: + type: string + format: date-time + description: When the alarm was acknowledged + readOnly: true + acknowledged_by: + type: string + description: User who acknowledged the alarm + readOnly: true + resolved_at: + type: string + format: date-time + description: When the alarm was resolved + readOnly: true + resolved_by: + type: string + description: User who resolved the alarm + readOnly: true + metadata: + type: object + description: Custom metadata + additionalProperties: true + + AlarmsPage: + type: object + properties: + offset: + type: integer + description: Number of items to skip during retrieval + minimum: 0 + default: 0 + limit: + type: integer + description: Size of the subset to retrieve + minimum: 1 + maximum: 1000 + default: 10 + total: + type: integer + description: Total number of results + minimum: 0 + alarms: + type: array + minItems: 0 + items: + $ref: '#/components/schemas/Alarm' + required: + - alarms + - total + - offset + - limit + + parameters: + DomainID: + name: domainID + description: Domain ID + in: path + required: true + schema: + type: string + AlarmID: + name: alarmID + description: Alarm ID + in: path + required: true + schema: + type: string + Offset: + name: offset + description: Number of items to skip + in: query + required: false + schema: + type: integer + default: 0 + minimum: 0 + Limit: + name: limit + description: Size of the subset to retrieve + in: query + required: false + schema: + type: integer + default: 10 + minimum: 1 + maximum: 1000 + Order: + name: order + description: Order by field + in: query + required: false + schema: + type: string + enum: [created_at, updated_at] + default: created_at + Dir: + name: dir + description: Sort direction + in: query + required: false + schema: + type: string + enum: [asc, desc] + default: desc + ChannelID: + name: channel_id + description: Filter by channel ID + in: query + required: false + schema: + type: string + ClientID: + name: client_id + description: Filter by client ID + in: query + required: false + schema: + type: string + Subtopic: + name: subtopic + description: Filter by subtopic + in: query + required: false + schema: + type: string + RuleID: + name: rule_id + description: Filter by rule ID + in: query + required: false + schema: + type: string + Status: + name: status + description: Filter by alarm status + in: query + required: false + schema: + type: string + enum: [active, cleared, all] + default: all + AssigneeID: + name: assignee_id + description: Filter by assignee ID + in: query + required: false + schema: + type: string + Severity: + name: severity + description: Filter by severity level + in: query + required: false + schema: + type: integer + minimum: 0 + maximum: 100 + UpdatedBy: + name: updated_by + description: Filter by user who updated + in: query + required: false + schema: + type: string + AssignedBy: + name: assigned_by + description: Filter by user who assigned + in: query + required: false + schema: + type: string + AcknowledgedBy: + name: acknowledged_by + description: Filter by user who acknowledged + in: query + required: false + schema: + type: string + ResolvedBy: + name: resolved_by + description: Filter by user who resolved + in: query + required: false + schema: + type: string + CreatedFrom: + name: created_from + description: Filter alarms created after this time (RFC3339 format) + in: query + required: false + schema: + type: string + format: date-time + CreatedTo: + name: created_to + description: Filter alarms created before this time (RFC3339 format) + in: query + required: false + schema: + type: string + format: date-time + + requestBodies: + AlarmUpdateReq: + description: JSON-formatted document describing the alarm update + required: true + content: + application/json: + schema: + type: object + properties: + status: + type: string + description: Alarm status + enum: [active, cleared] + assignee_id: + type: string + description: ID of the user assigned to this alarm + severity: + type: integer + description: Severity level (0-100) + minimum: 0 + maximum: 100 + metadata: + type: object + description: Custom metadata + additionalProperties: true + + responses: + AlarmRes: + description: Alarm data retrieved + content: + application/json: + schema: + $ref: '#/components/schemas/Alarm' + links: + update: + operationId: updateAlarm + parameters: + alarmID: $response.body#/id + domainID: $response.body#/domain_id + delete: + operationId: deleteAlarm + parameters: + alarmID: $response.body#/id + domainID: $response.body#/domain_id + AlarmsPageRes: + description: Alarms page retrieved + content: + application/json: + schema: + $ref: '#/components/schemas/AlarmsPage' + ServiceError: + description: Unexpected server-side error occurred + HealthRes: + description: Service Health Check + content: + application/health+json: + schema: + $ref: "./schemas/health_info.yaml" + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + * Users access: "Authorization: Bearer " diff --git a/bootstrap.yaml b/bootstrap.yaml new file mode 100644 index 000000000..b46c5da4d --- /dev/null +++ b/bootstrap.yaml @@ -0,0 +1,699 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala Bootstrap service + description: | + HTTP API for managing platform clients configuration. + Some useful links: + - [The Magistrala repository](https://github.com/absmach/magistrala) + contact: + email: info@absmach.eu + license: + name: Apache 2.0 + url: https://github.com/absmach/magistrala/blob/main/LICENSE + version: 0.18.5 + +servers: + - url: http://localhost:9013 + - url: https://localhost:9013 + +tags: + - name: configs + description: Everything about your Configs + externalDocs: + description: Find out more about Configs + url: https://docs.magistrala.absmach.eu + +paths: + /{domainID}/clients/configs: + post: + operationId: createConfig + summary: Adds new config + description: | + Adds new config to the list of config owned by user identified using + the provided access token. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + requestBody: + $ref: "#/components/requestBodies/ConfigCreateReq" + responses: + "201": + $ref: "#/components/responses/ConfigCreateRes" + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: A non-existent entity request. + "409": + description: Failed due to using an existing identity. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + "503": + description: Failed to receive response from the clients service. + get: + operationId: getConfigs + summary: Retrieves managed configs + description: | + Retrieves a list of managed configs. Due to performance concerns, data + is retrieved in subsets. The API configs must ensure that the entire + dataset is consumed either by making subsequent requests, or by + increasing the subset size of the initial request. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/Limit" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/State" + - $ref: "#/components/parameters/Name" + responses: + "200": + $ref: "#/components/responses/ConfigListRes" + "400": + description: Failed due to malformed query parameters. + "401": + description: Missing or invalid access token provided. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/clients/configs/{configID}: + get: + operationId: getConfig + summary: Retrieves config info (with channels). + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + responses: + "200": + $ref: "#/components/responses/ConfigRes" + "400": + description: Missing or invalid config. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: Config does not exist. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + put: + operationId: updateConfig + summary: Updates config info + description: | + Update is performed by replacing the current resource data with values + provided in a request payload. Note that the owner, ID, external ID, + external key, SuperMQ Client ID and key cannot be changed. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + requestBody: + $ref: "#/components/requestBodies/ConfigUpdateReq" + responses: + "200": + description: Config updated. + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: Config does not exist. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + delete: + operationId: removeConfig + summary: Removes a Config + description: | + Removes a Config. In case of successful removal the service will ensure + that the removed config is disconnected from all of the SuperMQ channels. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + responses: + "204": + description: Config removed. + "400": + description: Failed due to malformed config ID. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/clients/configs/certs/{configID}: + patch: + operationId: updateConfigCerts + summary: Updates certs + description: | + Update is performed by replacing the current certificate data with values + provided in a request payload. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + requestBody: + $ref: "#/components/requestBodies/ConfigCertUpdateReq" + responses: + "200": + description: Config updated. + $ref: "#/components/responses/ConfigUpdateCertsRes" + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: Config does not exist. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/clients/configs/connections/{configID}: + put: + operationId: updateConfigConnections + summary: Updates channels the client is connected to + description: | + Update connections performs update of the channel list corresponding + Client is connected to. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + requestBody: + $ref: "#/components/requestBodies/ConfigConnUpdateReq" + responses: + "200": + description: Config updated. + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: Config does not exist. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /clients/bootstrap/{externalId}: + get: + operationId: getBootstrapConfig + summary: Retrieves configuration. + description: | + Retrieves a configuration with given external ID and external key. + tags: + - configs + security: + - bootstrapAuth: [] + parameters: + - $ref: "#/components/parameters/ExternalId" + responses: + "200": + $ref: "#/components/responses/BootstrapConfigRes" + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid external key provided. + "404": + description: Failed to retrieve corresponding config. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /clients/bootstrap/secure/{externalId}: + get: + operationId: getSecureBootstrapConfig + summary: Retrieves configuration. + description: | + Retrieves a configuration with given external ID and encrypted external key. + tags: + - configs + security: + - bootstrapEncAuth: [] + parameters: + - $ref: "#/components/parameters/ExternalId" + responses: + "200": + $ref: "#/components/responses/BootstrapConfigRes" + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "404": + description: | + Failed to retrieve corresponding config. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/clients/state/{configID}: + put: + operationId: updateConfigState + summary: Updates Config state. + description: | + Updating state represents enabling/disabling Config, i.e. connecting + and disconnecting corresponding SuperMQ Client to the list of Channels. + tags: + - configs + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ConfigId" + requestBody: + $ref: "#/components/requestBodies/ConfigStateUpdateReq" + responses: + "204": + description: Config removed. + "400": + description: Failed due to malformed config's ID. + "401": + description: Missing or invalid access token provided. + "404": + description: A non-existent entity request. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /health: + get: + summary: Retrieves service health check info. + tags: + - health + security: [] + responses: + "200": + $ref: "#/components/responses/HealthRes" + "500": + $ref: "#/components/responses/ServiceError" + +components: + schemas: + State: + type: integer + enum: [0, 1] + Config: + type: object + properties: + client_id: + type: string + format: uuid + description: Corresponding SuperMQ Client ID. + magistrala_secret: + type: string + format: uuid + description: Corresponding SuperMQ Client key. + channels: + type: array + minItems: 0 + items: + type: object + properties: + id: + type: string + format: uuid + description: Channel unique identifier. + name: + type: string + description: Name of the Channel. + metadata: + type: object + description: Custom metadata related to the Channel. + external_id: + type: string + description: External ID (MAC address or some unique identifier). + external_key: + type: string + description: External key. + content: + type: string + description: Free-form custom configuration. + state: + $ref: "#/components/schemas/State" + client_cert: + type: string + description: Client certificate. + ca_cert: + type: string + description: Issuing CA certificate. + required: + - external_id + - external_key + ConfigList: + type: object + properties: + total: + type: integer + description: Total number of results. + minimum: 0 + offset: + type: integer + description: Number of items to skip during retrieval. + minimum: 0 + default: 0 + limit: + type: integer + description: Size of the subset to retrieve. + maximum: 100 + default: 10 + configs: + type: array + minItems: 0 + uniqueItems: true + items: + $ref: "#/components/schemas/Config" + required: + - configs + BootstrapConfig: + type: object + properties: + client_id: + type: string + format: uuid + description: Corresponding SuperMQ Client ID. + client_key: + type: string + format: uuid + description: Corresponding SuperMQ Client key. + channels: + type: array + minItems: 0 + items: + type: string + content: + type: string + description: Free-form custom configuration. + client_cert: + type: string + description: Client certificate. + required: + - client_id + - client_key + - channels + - content + ConfigUpdateCerts: + type: object + properties: + client_id: + type: string + format: uuid + description: Corresponding SuperMQ Client ID. + client_cert: + type: string + description: Client certificate. + client_key: + type: string + description: Key for the client_cert. + ca_cert: + type: string + description: Issuing CA certificate. + required: + - client_id + - client_key + - channels + - content + + parameters: + ConfigId: + name: configID + description: Unique Config identifier. It's the ID of the corresponding Client. + in: path + schema: + type: string + format: uuid + required: true + ExternalId: + name: externalId + description: Unique Config identifier provided by external entity. + in: path + schema: + type: string + required: true + Limit: + name: limit + description: Size of the subset to retrieve. + in: query + schema: + type: integer + default: 10 + maximum: 100 + minimum: 1 + required: false + Offset: + name: offset + description: Number of items to skip during retrieval. + in: query + schema: + type: integer + default: 0 + minimum: 0 + required: false + State: + name: state + description: A state of items + in: query + schema: + $ref: "#/components/schemas/State" + required: false + Name: + name: name + description: Name of the config. Search by name is partial-match and case-insensitive. + in: query + schema: + type: string + required: false + DomainID: + name: domainID + description: Unique domain identifier. + in: path + schema: + type: string + format: uuid + required: true + example: bb7edb32-2eac-4aad-aebe-ed96fe073879 + + requestBodies: + ConfigCreateReq: + description: JSON-formatted document describing the new config. + required: true + content: + application/json: + schema: + type: object + properties: + external_id: + type: string + description: External ID (MAC address or some unique identifier). + external_key: + type: string + description: External key. + client_id: + type: string + format: uuid + description: ID of the corresponding SuperMQ Client. + channels: + type: array + minItems: 0 + items: + type: string + format: uuid + content: + type: string + name: + type: string + client_cert: + type: string + description: Client Certificate. + client_key: + type: string + description: Client Private Key. + ca_cert: + type: string + required: + - external_id + - external_key + ConfigUpdateReq: + description: JSON-formatted document describing the updated client. + content: + application/json: + schema: + type: object + properties: + content: + type: string + name: + type: string + required: + - content + - name + ConfigCertUpdateReq: + description: JSON-formatted document describing the updated client. + content: + application/json: + schema: + type: object + properties: + client_cert: + type: string + client_key: + type: string + ca_cert: + type: string + ConfigConnUpdateReq: + description: Array if IDs the client is be connected to. + content: + application/json: + schema: + type: object + properties: + channels: + type: array + minItems: 0 + items: + type: string + format: uuid + ConfigStateUpdateReq: + description: Update the state of the Config. + content: + application/json: + schema: + type: object + properties: + state: + $ref: "#/components/schemas/State" + + responses: + ConfigCreateRes: + description: Config registered. + headers: + Location: + content: + text/plain: + schema: + type: string + description: Created configuration's relative URL (i.e. /clients/configs/{configID}). + ConfigListRes: + description: Data retrieved. Configs from this list don't contain channels. + content: + application/json: + schema: + $ref: "#/components/schemas/ConfigList" + ConfigRes: + description: Data retrieved. + content: + application/json: + schema: + $ref: "#/components/schemas/Config" + links: + update: + operationId: updateConfig + parameters: + configID: $response.body#/id + updateCerts: + operationId: updateConfigCerts + parameters: + configID: $response.body#/id + updateConnections: + operationId: updateConfigConnections + parameters: + configID: $response.body#/id + updateState: + operationId: updateConfigState + parameters: + configID: $response.body#/id + delete: + operationId: removeConfig + parameters: + configID: $response.body#/id + BootstrapConfigRes: + description: | + Data retrieved. If secure, a response is encrypted using + the secret key, so the response is in the binary form. + content: + application/json: + schema: + $ref: "#/components/schemas/BootstrapConfig" + ServiceError: + description: Unexpected server-side error occurred. + HealthRes: + description: Service Health Check. + content: + application/health+json: + schema: + $ref: "./schemas/health_info.yaml" + ConfigUpdateCertsRes: + description: Data retrieved. Config certs updated. + content: + application/json: + schema: + $ref: "#/components/schemas/ConfigUpdateCerts" + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + * Users access: "Authorization: Bearer " + + bootstrapAuth: + type: http + scheme: bearer + bearerFormat: string + description: | + * Clients access: "Authorization: Client " + + bootstrapEncAuth: + type: http + scheme: bearer + bearerFormat: aes-sha256-uuid + description: | + * Clients access: "Authorization: Client " + Hex-encoded configuration external key encrypted using + the AES algorithm and SHA256 sum of the external key + itself as an encryption key. + +security: + - bearerAuth: [] diff --git a/index.html b/index.html new file mode 100644 index 000000000..ff059292d --- /dev/null +++ b/index.html @@ -0,0 +1,181 @@ + + + + + + + Magistrala API Documentation + + + + +
+

Magistrala API Documentation

+
+ + +
+
+
+ + + + + + diff --git a/notifiers.yaml b/notifiers.yaml new file mode 100644 index 000000000..a559193bc --- /dev/null +++ b/notifiers.yaml @@ -0,0 +1,292 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala Notifiers service + description: | + HTTP API for Notifiers service. + Some useful links: + - [The Magistrala repository](https://github.com/absmach/magistrala) + contact: + email: info@absmach.eu + license: + name: Apache 2.0 + url: https://github.com/absmach/magistrala/blob/main/LICENSE + version: 0.18.5 + +servers: + - url: http://localhost:9014 + - url: https://localhost:9014 + - url: http://localhost:9015 + - url: https://localhost:9015 + +tags: + - name: notifiers + description: Everything about your Notifiers + externalDocs: + description: Find out more about notifiers + url: https://docs.magistrala.absmach.eu + +paths: + /subscriptions: + post: + operationId: createSubscription + summary: Create subscription + description: Creates a new subscription give a topic and contact. + tags: + - notifiers + requestBody: + $ref: "#/components/requestBodies/Create" + responses: + "201": + $ref: "#/components/responses/Create" + "400": + description: Failed due to malformed JSON. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "409": + description: Failed due to using an existing topic and contact. + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + get: + operationId: listSubscriptions + summary: List subscriptions + description: List subscriptions given list parameters. + tags: + - notifiers + parameters: + - $ref: "#/components/parameters/Topic" + - $ref: "#/components/parameters/Contact" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Limit" + responses: + "200": + $ref: "#/components/responses/Page" + "400": + description: Failed due to malformed query parameters. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: A non-existent entity request. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + /subscriptions/{id}: + get: + operationId: viewSubscription + summary: Get subscription with the provided id + description: Retrieves a subscription with the provided id. + tags: + - notifiers + parameters: + - $ref: "#/components/parameters/Id" + responses: + "200": + $ref: "#/components/responses/View" + "400": + description: Failed due to malformed ID. + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: A non-existent entity request. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + delete: + operationId: removeSubscription + summary: Delete subscription with the provided id + description: Removes a subscription with the provided id. + tags: + - notifiers + parameters: + - $ref: "#/components/parameters/Id" + responses: + "204": + description: Subscription removed + "401": + description: Missing or invalid access token provided. + "403": + description: Failed to perform authorization over the entity. + "404": + description: A non-existent entity request. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + /health: + get: + summary: Retrieves service health check info. + tags: + - health + security: [] + responses: + "200": + $ref: "#/components/responses/HealthRes" + "500": + $ref: "#/components/responses/ServiceError" + +components: + schemas: + Subscription: + type: object + properties: + id: + type: string + format: ulid + example: 01EWDVKBQSG80B6PQRS9PAAY35 + description: ULID id of the subscription. + owner_id: + type: string + format: uuid + example: 18167738-f7a8-4e96-a123-58c3cd14de3a + description: An id of the owner who created subscription. + topic: + type: string + example: topic.subtopic + description: Topic to which the user subscribes. + contact: + type: string + example: user@example.com + description: The contact of the user to which the notification will be sent. + CreateSubscription: + type: object + properties: + topic: + type: string + example: topic.subtopic + description: Topic to which the user subscribes. + contact: + type: string + example: user@example.com + description: The contact of the user to which the notification will be sent. + Page: + type: object + properties: + subscriptions: + type: array + minItems: 0 + uniqueItems: true + items: + $ref: "#/components/schemas/Subscription" + total: + type: integer + description: Total number of items. + offset: + type: integer + description: Number of items to skip during retrieval. + limit: + type: integer + description: Maximum number of items to return in one page. + + parameters: + Id: + name: id + description: Unique identifier. + in: path + schema: + type: string + format: ulid + required: true + Limit: + name: limit + description: Size of the subset to retrieve. + in: query + schema: + type: integer + default: 10 + maximum: 100 + minimum: 1 + required: false + Offset: + name: offset + description: Number of items to skip during retrieval. + in: query + schema: + type: integer + default: 0 + minimum: 0 + required: false + Topic: + name: topic + description: Topic name. + in: query + schema: + type: string + required: false + Contact: + name: contact + description: Subscription contact. + in: query + schema: + type: string + required: false + + requestBodies: + Create: + description: JSON-formatted document describing the new subscription to be created + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateSubscription" + + responses: + Create: + description: Created a new subscription. + headers: + Location: + content: + text/plain: + schema: + type: string + description: Created subscription relative URL + example: /subscriptions/{id} + View: + description: View subscription. + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + links: + delete: + operationId: removeSubscription + parameters: + id: $response.body#/id + Page: + description: Data retrieved. + content: + application/json: + schema: + $ref: "#/components/schemas/Page" + ServiceError: + description: Unexpected server-side error occurred. + HealthRes: + description: Service Health Check. + content: + application/health+json: + schema: + $ref: "./schemas/health_info.yaml" + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + * Users access: "Authorization: Bearer " + +security: + - bearerAuth: [] diff --git a/readers.yaml b/readers.yaml new file mode 100644 index 000000000..607e21b43 --- /dev/null +++ b/readers.yaml @@ -0,0 +1,312 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala reader service + description: | + HTTP API for reading messages. + Some useful links: + - [The Magistrala repository](https://github.com/absmach/magistrala) + contact: + email: info@absmach.eu + license: + name: Apache 2.0 + url: https://github.com/absmach/magistrala/blob/main/LICENSE + version: 0.18.5 + +servers: + - url: http://localhost:9003 + - url: https://localhost:9003 + - url: http://localhost:9005 + - url: https://localhost:9005 + - url: http://localhost:9009 + - url: https://localhost:9009 + - url: http://localhost:9011 + - url: https://localhost:9011 + +tags: + - name: readers + description: Everything about your Readers + externalDocs: + description: Find out more about readers + url: https://docs.magistrala.absmach.eu + +paths: + /{domainID}/channels/{chanId}/messages: + get: + operationId: getMessages + summary: Retrieves messages sent to single channel + description: | + Retrieves a list of messages sent to specific channel. Due to + performance concerns, data is retrieved in subsets. The API readers must + ensure that the entire dataset is consumed either by making subsequent + requests, or by increasing the subset size of the initial request. + tags: + - readers + parameters: + - $ref: "#/components/parameters/DomainID" + - $ref: "#/components/parameters/ChanId" + - $ref: "#/components/parameters/Limit" + - $ref: "#/components/parameters/Offset" + - $ref: "#/components/parameters/Publisher" + - $ref: "#/components/parameters/Name" + - $ref: "#/components/parameters/Value" + - $ref: "#/components/parameters/BoolValue" + - $ref: "#/components/parameters/StringValue" + - $ref: "#/components/parameters/DataValue" + - $ref: "#/components/parameters/From" + - $ref: "#/components/parameters/To" + - $ref: "#/components/parameters/Aggregation" + - $ref: "#/components/parameters/Interval" + responses: + "200": + $ref: "#/components/responses/MessagesPageRes" + "400": + description: Failed due to malformed query parameters. + "401": + description: Missing or invalid access token provided. + "500": + $ref: "#/components/responses/ServiceError" + /health: + get: + operationId: health + summary: Retrieves service health check info. + tags: + - health + security: [] + responses: + "200": + $ref: "#/components/responses/HealthRes" + "500": + $ref: "#/components/responses/ServiceError" + +components: + schemas: + MessagesPage: + type: object + properties: + total: + type: number + description: Total number of items that are present on the system. + offset: + type: number + description: Number of items that were skipped during retrieval. + limit: + type: number + description: Size of the subset that was retrieved. + messages: + type: array + minItems: 0 + uniqueItems: true + items: + type: object + properties: + channel: + type: integer + description: Unique channel id. + publisher: + type: integer + description: Unique publisher id. + protocol: + type: string + description: Protocol name. + name: + type: string + description: Measured parameter name. + unit: + type: string + description: Value unit. + value: + type: number + description: Measured value in number. + stringValue: + type: string + description: Measured value in string format. + boolValue: + type: boolean + description: Measured value in boolean format. + dataValue: + type: string + description: Measured value in binary format. + valueSum: + type: number + description: Sum value. + time: + type: number + description: Time of measurement. + updateTime: + type: number + description: Time of updating measurement. + + parameters: + DomainID: + name: domainID + description: Unique domain identifier. + in: path + schema: + type: string + format: uuid + required: true + ChanId: + name: chanId + description: Unique channel identifier. + in: path + schema: + type: string + format: uuid + required: true + Limit: + name: limit + description: Size of the subset to retrieve. + in: query + schema: + type: integer + default: 10 + maximum: 100 + minimum: 1 + required: false + Offset: + name: offset + description: Number of items to skip during retrieval. + in: query + schema: + type: integer + default: 0 + minimum: 0 + required: false + Publisher: + name: Publisher + description: Unique thing identifier. + in: query + schema: + type: string + format: uuid + required: false + Name: + name: name + description: SenML message name. + in: query + schema: + type: string + required: false + Value: + name: v + description: SenML message value. + in: query + schema: + type: string + required: false + BoolValue: + name: vb + description: SenML message bool value. + in: query + schema: + type: boolean + required: false + StringValue: + name: vs + description: SenML message string value. + in: query + schema: + type: string + required: false + DataValue: + name: vd + description: SenML message data value. + in: query + schema: + type: string + required: false + Comparator: + name: comparator + description: Value comparison operator. + in: query + schema: + type: string + default: eq + enum: + - eq + - lt + - le + - gt + - ge + required: false + From: + name: from + description: SenML message time in nanoseconds (integer part represents seconds). + in: query + schema: + type: number + example: 1709218556069 + required: false + To: + name: to + description: SenML message time in nanoseconds (integer part represents seconds). + in: query + schema: + type: number + example: 1709218757503 + required: false + Aggregation: + name: aggregation + description: Aggregation function. + in: query + schema: + type: string + enum: + - MAX + - AVG + - MIN + - SUM + - COUNT + - max + - min + - sum + - avg + - count + example: MAX + required: false + Interval: + name: interval + description: Aggregation interval. + in: query + schema: + type: string + example: 10s + required: false + + responses: + MessagesPageRes: + description: Data retrieved. + content: + application/json: + schema: + $ref: "#/components/schemas/MessagesPage" + ServiceError: + description: Unexpected server-side error occurred. + HealthRes: + description: Service Health Check. + content: + application/health+json: + schema: + $ref: "./schemas/health_info.yaml" + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + * Users access: "Authorization: Bearer " + + thingAuth: + type: http + scheme: bearer + bearerFormat: uuid + description: | + * Things access: "Authorization: Thing " + +security: + - bearerAuth: [] + - thingAuth: [] diff --git a/reports.yaml b/reports.yaml new file mode 100644 index 000000000..49a4c41ef --- /dev/null +++ b/reports.yaml @@ -0,0 +1,556 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala Reports Service API + description: | + HTTP API for managing reports service. + version: 0.18.5 +servers: + - url: http://localhost:9017 +tags: + - name: reports + description: Operations related to report configurations and generation +paths: + /{domainID}/reports: + post: + operationId: generateReport + summary: Generate a report + description: Generates a report based on the provided configuration or an existing config. The action determines the response format. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + security: + - bearerAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GenerateReportRequest' + responses: + '200': + description: Report generated successfully (content varies by action) + content: + application/json: + schema: + $ref: '#/components/schemas/GenerateReportResponse' + application/octet-stream: + schema: + type: string + format: binary + '400': + description: Invalid request parameters + '401': + description: Missing or invalid access token + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/reports/configs: + post: + operationId: addReportConfig + summary: Create a report configuration + description: Creates a new report configuration. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + security: + - bearerAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddReportConfigRequest' + responses: + '201': + description: Report configuration created + headers: + Location: + schema: + type: string + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '400': + description: Invalid request body + '401': + description: Missing or invalid access token + '500': + $ref: '#/components/responses/ServiceError' + get: + operationId: listReportConfigs + summary: List report configurations + description: Retrieves a paginated list of report configurations. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + security: + - bearerAuth: [] + responses: + '200': + description: List of report configurations + content: + application/json: + schema: + $ref: '#/components/schemas/ListReportsConfigResponse' + '400': + description: Invalid query parameters + '401': + description: Missing or invalid access token + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/reports/configs/{reportID}: + get: + operationId: viewReportConfig + summary: View a report configuration + description: Retrieves details of a specific report configuration. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + responses: + '200': + description: Report configuration details + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '404': + description: Report configuration not found + '401': + description: Missing or invalid access token + '500': + $ref: '#/components/responses/ServiceError' + patch: + operationId: updateReportConfig + summary: Update a report configuration + description: Updates specified fields of a report configuration. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateReportConfigRequest' + responses: + '200': + description: Report configuration updated + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '400': + description: Invalid request body + '401': + description: Missing or invalid access token + '404': + description: Report configuration not found + '500': + $ref: '#/components/responses/ServiceError' + delete: + operationId: deleteReportConfig + summary: Delete a report configuration + description: Permanently deletes a report configuration. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + responses: + '204': + description: Report configuration deleted + '401': + description: Missing or invalid access token + '404': + description: Report configuration not found + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/reports/configs/{reportID}/schedule: + patch: + operationId: updateReportSchedule + summary: Update report schedule + description: Updates the schedule of a report configuration. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Schedule' + responses: + '200': + description: Schedule updated + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '400': + description: Invalid schedule + '401': + description: Missing or invalid access token + '404': + description: Report configuration not found + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/reports/configs/{reportID}/enable: + post: + operationId: enableReportConfig + summary: Enable a report configuration + description: Enables a report configuration to generate scheduled reports. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + responses: + '200': + description: Report configuration enabled + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '401': + description: Missing or invalid access token + '404': + description: Report configuration not found + '500': + $ref: '#/components/responses/ServiceError' + + /{domainID}/reports/configs/{reportID}/disable: + post: + operationId: disableReportConfig + summary: Disable a report configuration + description: Disables a report configuration, stopping scheduled reports. + tags: + - reports + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/ReportID' + security: + - bearerAuth: [] + responses: + '200': + description: Report configuration disabled + content: + application/json: + schema: + $ref: '#/components/schemas/ReportConfig' + '401': + description: Missing or invalid access token + '404': + description: Report configuration not found + '500': + $ref: '#/components/responses/ServiceError' + + /health: + get: + summary: Service health check + tags: + - health + responses: + '200': + $ref: '#/components/responses/HealthRes' + +components: + schemas: + ReportConfig: + type: object + properties: + id: + type: string + readOnly: true + name: + type: string + description: + type: string + domain_id: + type: string + readOnly: true + schedule: + $ref: '#/components/schemas/Schedule' + config: + $ref: '#/components/schemas/MetricConfig' + email: + $ref: '#/components/schemas/EmailSetting' + metrics: + type: array + items: + $ref: '#/components/schemas/ReqMetric' + status: + $ref: '#/components/schemas/Status' + created_at: + type: string + format: date-time + readOnly: true + created_by: + type: string + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + updated_by: + type: string + readOnly: true + required: + - name + - metrics + - config + + Schedule: + type: object + properties: + recurring: + type: string + enum: [None, Daily, Weekly, Monthly] + recurring_period: + type: integer + minimum: 1 + start_time: + type: string + format: date-time + next_run: + type: string + format: date-time + readOnly: true + + MetricConfig: + type: object + properties: + title: + type: string + maxLength: 100 + format: + type: string + enum: [pdf, csv, html] + aggregation: + $ref: '#/components/schemas/AggConfig' + + AggConfig: + type: object + properties: + window: + type: string + function: + type: string + enum: [sum, average, max, min] + + EmailSetting: + type: object + properties: + recipients: + type: array + items: + type: string + format: email + subject: + type: string + body_template: + type: string + required: + - recipients + - subject + + ReqMetric: + type: object + properties: + name: + type: string + type: + type: string + enum: [gauge, counter, histogram] + parameters: + type: object + required: + - name + - type + + Status: + type: string + enum: [enabled, disabled] + + GenerateReportRequest: + type: object + properties: + action: + type: string + enum: [view, download, email] + config_id: + type: string + name: + type: string + description: + type: string + schedule: + $ref: '#/components/schemas/Schedule' + config: + $ref: '#/components/schemas/MetricConfig' + email: + $ref: '#/components/schemas/EmailSetting' + metrics: + type: array + items: + $ref: '#/components/schemas/ReqMetric' + required: + - action + + GenerateReportResponse: + type: object + properties: + total: + type: integer + from: + type: string + format: date-time + to: + type: string + format: date-time + aggregation: + $ref: '#/components/schemas/AggConfig' + reports: + type: array + items: + $ref: '#/components/schemas/Report' + + Report: + type: object + properties: + timestamp: + type: string + format: date-time + value: + type: number + metric_name: + type: string + + AddReportConfigRequest: + type: object + properties: + name: + type: string + description: + type: string + schedule: + $ref: '#/components/schemas/Schedule' + config: + $ref: '#/components/schemas/MetricConfig' + email: + $ref: '#/components/schemas/EmailSetting' + metrics: + type: array + items: + $ref: '#/components/schemas/ReqMetric' + status: + $ref: '#/components/schemas/Status' + required: + - name + - metrics + - config + + UpdateReportConfigRequest: + type: object + properties: + name: + type: string + description: + type: string + schedule: + $ref: '#/components/schemas/Schedule' + config: + $ref: '#/components/schemas/MetricConfig' + email: + $ref: '#/components/schemas/EmailSetting' + metrics: + type: array + items: + $ref: '#/components/schemas/ReqMetric' + status: + $ref: '#/components/schemas/Status' + + ListReportsConfigResponse: + type: object + properties: + total: + type: integer + offset: + type: integer + limit: + type: integer + report_configs: + type: array + items: + $ref: '#/components/schemas/ReportConfig' + + parameters: + DomainID: + name: domainID + in: path + required: true + schema: + type: string + ReportID: + name: reportID + in: path + required: true + schema: + type: string + Offset: + name: offset + in: query + schema: + type: integer + default: 0 + minimum: 0 + Limit: + name: limit + in: query + schema: + type: integer + default: 10 + minimum: 1 + maximum: 100 + + responses: + ServiceError: + description: Unexpected server error + HealthRes: + description: Service health status + content: + application/json: + schema: + type: object + properties: + status: + type: string + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT diff --git a/rules.yaml b/rules.yaml new file mode 100644 index 000000000..160a19c02 --- /dev/null +++ b/rules.yaml @@ -0,0 +1,586 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +openapi: 3.0.1 +info: + title: Magistrala Rules Engine API + description: | + HTTP API for managing rules engine service. + Some useful links: + - [The Magistrala repository](https://github.com/absmach/magistrala) + contact: + email: info@absmach.eu + license: + name: Apache 2.0 + url: https://github.com/absmach/magistrala/blob/main/LICENSE + version: 0.18.5 + +servers: + - url: http://localhost:9008 + - url: http://localhost:9008 + +tags: + - name: rules engine + description: Everything about your Rules Engine + externalDocs: + description: Find out more about rules engine + url: https://docs.magistrala.absmach.eu + +paths: + /{domainID}/rules: + post: + operationId: createRule + summary: Create Rule + description: | + Creates a new rule for message processing + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + security: + - bearerAuth: [] + requestBody: + $ref: '#/components/requestBodies/RuleCreateReq' + responses: + '201': + $ref: '#/components/responses/RuleCreateRes' + '400': + description: Failed due to malformed JSON + '401': + description: Missing or invalid access token + '415': + description: Missing or invalid content type + "500": + $ref: "#/components/responses/ServiceError" + "503": + description: Failed to receive response from the clients service. + get: + operationId: getRules + summary: List Rules + description: | + Retrieves a list of rules with optional filtering + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/InputChannel' + - $ref: '#/components/parameters/OutputChannel' + - $ref: '#/components/parameters/Status' + security: + - bearerAuth: [] + responses: + '200': + $ref: '#/components/responses/RuleListRes' + '400': + description: Failed due to malformed query parameters + '401': + description: Missing or invalid access token + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/rules/{ruleID}: + get: + operationId: getRule + summary: View Rule + description: Retrieves a rule by ID + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/RuleID' + security: + - bearerAuth: [] + responses: + '200': + $ref: '#/components/responses/RuleRes' + "400": + description: Missing or invalid rule + "403": + description: Failed to perform authorization over the entity + '401': + description: Missing or invalid access token + '404': + description: Rule does not exist + "422": + description: Database can't process request + "500": + $ref: "#/components/responses/ServiceError" + put: + operationId: updateRule + summary: Update Rule + description: Updates an existing rule + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/RuleID' + security: + - bearerAuth: [] + requestBody: + $ref: '#/components/requestBodies/RuleUpdateReq' + responses: + '200': + $ref: '#/components/responses/RuleRes' + '400': + description: Failed due to malformed JSON + '401': + description: Missing or invalid access token + '404': + description: Rule does not exist + "415": + description: Missing or invalid content type. + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + delete: + operationId: removeRule + summary: Delete Rule + description: Deletes a rule + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/RuleID' + security: + - bearerAuth: [] + responses: + '204': + description: Rule deleted successfully + "400": + description: Failed due to malformed rule ID + '401': + description: Missing or invalid access token + "403": + description: Failed to perform authorization over the entity + "422": + description: Database can't process request + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/rules/{ruleID}/enable: + put: + operationId: enableRule + summary: Enable Rule + description: Enables a rule for processing + tags: + - rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/RuleID' + security: + - bearerAuth: [] + responses: + '200': + description: Rule enabled successfully + "400": + description: Failed due to malformed JSON + '401': + description: Missing or invalid access token + "403": + description: Failed to perform authorization over the entity + '404': + description: Rule does not exist + "422": + description: Database can't process request. + "500": + $ref: "#/components/responses/ServiceError" + + /{domainID}/rules/{ruleID}/disable: + put: + operationId: disableRule + summary: Disable Rule + description: Disables a rule from processing + tags: + - Rules + parameters: + - $ref: '#/components/parameters/DomainID' + - $ref: '#/components/parameters/RuleID' + security: + - bearerAuth: [] + responses: + '200': + description: Rule disabled successfully + "400": + description: Failed due to malformed JSON + '401': + description: Missing or invalid access token + "403": + description: Failed to perform authorization over the entity + '404': + description: Rule does not exist + "422": + description: Database can't process request + "500": + $ref: "#/components/responses/ServiceError" + + /health: + get: + summary: Retrieves service health check info. + tags: + - health + security: [] + responses: + "200": + $ref: "#/components/responses/HealthRes" + "500": + $ref: "#/components/responses/ServiceError" + +components: + schemas: + RulesListRes: + type: object + properties: + total: + type: integer + description: Total number of results + minimum: 0 + offset: + type: integer + description: Number of items to skip during retrieval + minimum: 0 + default: 0 + limit: + type: integer + description: Size of the subset to retrieve + maximum: 100 + default: 10 + rules: + type: array + minItems: 0 + uniqueItems: true + items: + $ref: '#/components/schemas/Rule' + required: + - rules + + Rule: + type: object + properties: + id: + type: string + description: Unique rule identifier + name: + type: string + description: Rule name + domain: + type: string + description: Domain ID this rule belongs to + metadata: + type: object + description: Custom metadata + additionalProperties: + type: string + input_channel: + type: string + description: Input channel for receiving messages + input_topic: + type: string + description: Input topic for receiving messages + logic: + type: object + description: Rule processing logic script + properties: + script: + type: string + description: Script content + output_channel: + type: string + description: Output channel for processed messages + output_topic: + type: string + description: Output topic for processed messages + schedule: + type: object + description: Rule execution schedule + properties: + start_datetime: + type: string + format: date-time + description: When the schedule becomes active + time: + type: string + format: date-time + description: Specific time for the rule to run + recurring: + type: string + description: Schedule recurrence pattern + enum: [None, Daily, Weekly, Monthly] + recurring_period: + type: integer + minimum: 1 + description: Controls how many intervals to skip between executions (1 = every interval, 2 = every second interval, etc.) + status: + type: string + description: Rule status + enum: [enabled, disabled] + created_at: + type: string + format: date-time + description: Creation timestamp + readOnly: true + created_by: + type: string + description: User who created the rule + updated_at: + type: string + format: date-time + description: Last update timestamp + readOnly: true + updated_by: + type: string + description: User who last updated the rule + required: + - name + - domain + - input_channel + - input_topic + - logic + - status + + parameters: + DomainID: + name: domainID + description: Domain ID + in: path + required: true + schema: + type: string + RuleID: + name: ruleID + description: Rule ID + in: path + required: true + schema: + type: string + Offset: + name: offset + description: Number of items to skip + in: query + required: false + schema: + type: integer + default: 0 + minimum: 0 + Limit: + name: limit + description: Size of the subset + in: query + required: false + schema: + type: integer + default: 10 + minimum: 1 + InputChannel: + name: input_channel + description: Filter by input channel + in: query + required: false + schema: + type: string + OutputChannel: + name: output_channel + description: Filter by output channel + in: query + required: false + schema: + type: string + Status: + name: status + description: Filter by rule status + in: query + required: false + schema: + type: string + enum: [enabled, disabled] + default: enabled + + requestBodies: + RuleCreateReq: + description: JSON-formatted document describing the new rule + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: Rule name + domain: + type: string + description: Domain ID this rule belongs to + metadata: + type: object + description: Custom metadata + additionalProperties: + type: string + input_channel: + type: string + description: Input channel for receiving messages + input_topic: + type: string + description: Input topic for receiving messages + logic: + type: object + description: Rule processing logic script + properties: + script: + type: string + description: Script content + output_channel: + type: string + description: Output channel for processed messages + output_topic: + type: string + description: Output topic for processed messages + schedule: + type: object + description: Rule execution schedule + properties: + start_datetime: + type: string + format: date-time + description: When the schedule becomes active + time: + type: string + format: date-time + description: Specific time for the rule to run + recurring: + type: string + description: Schedule recurrence pattern + enum: [None, Daily, Weekly, Monthly] + recurring_period: + type: integer + minimum: 1 + description: Controls how many intervals to skip between executions + status: + type: string + description: Rule status + enum: [enabled, disabled] + required: + - name + - domain + - input_channel + - input_topic + - logic + - schedule + RuleUpdateReq: + description: JSON-formatted document describing the rule update + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: Rule name + metadata: + type: object + description: Custom metadata + additionalProperties: + type: string + input_channel: + type: string + description: Input channel for receiving messages + input_topic: + type: string + description: Input topic for receiving messages + logic: + type: object + description: Rule processing logic script + properties: + script: + type: string + description: Script content + output_channel: + type: string + description: Output channel for processed messages + output_topic: + type: string + description: Output topic for processed messages + schedule: + type: object + description: Rule execution schedule + properties: + start_datetime: + type: string + format: date-time + description: When the schedule becomes active + time: + type: string + format: date-time + description: Specific time for the rule to run + recurring: + type: string + description: Schedule recurrence pattern + enum: [None, Daily, Weekly, Monthly] + recurring_period: + type: integer + minimum: 1 + description: Controls how many intervals to skip between executions + status: + type: string + description: Rule status + enum: [enabled, disabled] + + responses: + RuleCreateRes: + description: Rule registered + headers: + Location: + content: + text/plain: + schema: + type: string + description: Created rule's relative URL (i.e. /rules/{ruleID}) + RuleListRes: + description: Data retrieved + content: + application/json: + schema: + $ref: '#/components/schemas/RulesListRes' + RuleRes: + description: Data retrieved + content: + application/json: + schema: + $ref: '#/components/schemas/Rule' + links: + update: + operationId: updateRule + parameters: + ruleID: $response.body#/id + enable: + operationId: enableRule + parameters: + ruleID: $response.body#/id + disable: + operationId: disableRule + parameters: + ruleID: $response.body#/id + delete: + operationId: removeRule + parameters: + ruleID: $response.body#/id + ServiceError: + description: Unexpected server-side error occurred + HealthRes: + description: Service Health Check + content: + application/health+json: + schema: + $ref: "./schemas/health_info.yaml" + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + * Users access: "Authorization: Bearer " diff --git a/schemas/health_info.yaml b/schemas/health_info.yaml new file mode 100644 index 000000000..9c4e8585d --- /dev/null +++ b/schemas/health_info.yaml @@ -0,0 +1,30 @@ +# Copyright (c) Abstract Machines +# SPDX-License-Identifier: Apache-2.0 + +type: object +properties: + status: + type: string + description: Service status. + enum: + - pass + version: + type: string + description: Service version. + example: v0.14.0 + commit: + type: string + description: Service commit hash. + example: 73362210dd2e04e389eaddb802cab3fe03976593 + description: + type: string + description: Service description. + example: service + build_time: + type: string + description: Service build time. + example: 2024-02-01_12:18:15 + instance_id: + type: string + description: Service instance ID. + example: 8edbf8af-7db7-4218-bb4f-a8a929ff5266