commit b182aa2ceb8950c340b8d5a06f2c34551e0e110b Author: dborovcanin Date: Mon Apr 6 20:29:04 2026 +0000 deploy: 94255e239330385e9a7b7ce838205edf1a13901b 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