mirror of
https://github.com/absmach/magistrala.git
synced 2026-06-23 04:10:28 +00:00
Dušan Borovčanin
427 lines
12 KiB
YAML
427 lines
12 KiB
YAML
# Copyright (c) Abstract Machines
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
openapi: 3.0.3
|
|
info:
|
|
title: Magistrala Journal Log Service
|
|
description: |
|
|
This is the Journal Log Server based on the OpenAPI 3.0 specification. It is the HTTP API for viewing journal log history. You can now help us improve the API whether it's by making changes to the definition itself or to the code.
|
|
Some useful links:
|
|
- [The Magistrala repository](https://github.com/absmach/magistrala)
|
|
contact:
|
|
email: info@mainflux.com
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://github.com/absmach/magistrala/blob/main/LICENSE
|
|
version: 0.18.0
|
|
|
|
servers:
|
|
- url: http://localhost:9021
|
|
- url: https://localhost:9021
|
|
|
|
tags:
|
|
- name: journal-log
|
|
description: Everything about your Journal Log
|
|
externalDocs:
|
|
description: Find out more about Journal Log
|
|
url: http://docs.mainflux.io/
|
|
|
|
paths:
|
|
/journal/user/{userID}:
|
|
get:
|
|
tags:
|
|
- journal-log
|
|
summary: List user journal log
|
|
description: |
|
|
Retrieves a list of journal. Due to performance concerns, data
|
|
is retrieved in subsets. The API must ensure that the entire
|
|
dataset is consumed either by making subsequent requests, or by
|
|
increasing the subset size of the initial request.
|
|
parameters:
|
|
- $ref: "#/components/parameters/user_id"
|
|
- $ref: "#/components/parameters/offset"
|
|
- $ref: "#/components/parameters/limit"
|
|
- $ref: "#/components/parameters/operation"
|
|
- $ref: "#/components/parameters/with_attributes"
|
|
- $ref: "#/components/parameters/with_metadata"
|
|
- $ref: "#/components/parameters/from"
|
|
- $ref: "#/components/parameters/to"
|
|
- $ref: "#/components/parameters/dir"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/JournalsPageRes"
|
|
"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"
|
|
|
|
/{domainID}/journal/client/{clientID}/telemetry:
|
|
get:
|
|
tags:
|
|
- journal-log
|
|
summary: View client telemetry
|
|
description: |
|
|
Retrieves telemetry data for a specific client within a domain.
|
|
This includes connection status, messages sent/received, and other metrics.
|
|
parameters:
|
|
- $ref: "#/components/parameters/domain_id"
|
|
- $ref: "#/components/parameters/client_id"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
description: Client telemetry data retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Telemetry"
|
|
"400":
|
|
description: Failed due to malformed request parameters.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Client not found.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/{domainID}/journal/{entityType}/{id}:
|
|
get:
|
|
tags:
|
|
- journal-log
|
|
summary: List entity journal log
|
|
description: |
|
|
Retrieves a list of journal. Due to performance concerns, data
|
|
is retrieved in subsets. The API must ensure that the entire
|
|
dataset is consumed either by making subsequent requests, or by
|
|
increasing the subset size of the initial request.
|
|
parameters:
|
|
- $ref: "#/components/parameters/domain_id"
|
|
- $ref: "#/components/parameters/entity_type"
|
|
- $ref: "#/components/parameters/id"
|
|
- $ref: "#/components/parameters/offset"
|
|
- $ref: "#/components/parameters/limit"
|
|
- $ref: "#/components/parameters/operation"
|
|
- $ref: "#/components/parameters/with_attributes"
|
|
- $ref: "#/components/parameters/with_metadata"
|
|
- $ref: "#/components/parameters/from"
|
|
- $ref: "#/components/parameters/to"
|
|
- $ref: "#/components/parameters/dir"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/JournalsPageRes"
|
|
"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"
|
|
|
|
/health:
|
|
get:
|
|
summary: Retrieves service health check info.
|
|
tags:
|
|
- health
|
|
security: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/HealthRes"
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
components:
|
|
schemas:
|
|
Telemetry:
|
|
type: object
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier of the client
|
|
example: "bb7edb32-2eac-4aad-aebe-ed96fe073879"
|
|
domain_id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier of the domain
|
|
example: "29d425c8-542b-4614-8a4d-a5951945d720"
|
|
subscriptions:
|
|
type: integer
|
|
format: int64
|
|
description: Number of active subscriptions for the client
|
|
example: 5
|
|
inbound_messages:
|
|
type: integer
|
|
format: int64
|
|
description: Number of messages received by the client
|
|
example: 1234567
|
|
outbound_messages:
|
|
type: integer
|
|
format: int64
|
|
description: Number of messages sent by the client
|
|
example: 987654
|
|
first_seen:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the client was first seen
|
|
example: "2024-01-11T10:00:00.000Z"
|
|
last_seen:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the client was last seen
|
|
example: "2024-01-11T12:05:07.449053Z"
|
|
|
|
Journal:
|
|
type: object
|
|
properties:
|
|
operation:
|
|
type: string
|
|
example: user.create
|
|
description: Journal operation.
|
|
occurred_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2024-01-11T12:05:07.449053Z"
|
|
description: Time when the journal occurred.
|
|
attributes:
|
|
type: object
|
|
description: Journal attributes.
|
|
example:
|
|
{
|
|
"created_at": "2024-06-12T11:34:32.991591Z",
|
|
"id": "29d425c8-542b-4614-8a4d-a5951945d720",
|
|
"identity": "Gawne-Havlicek@email.com",
|
|
"name": "Newgard-Frisina",
|
|
"status": "enabled",
|
|
"updated_at": "2024-06-12T11:34:33.116795Z",
|
|
"updated_by": "ad228f20-4741-47c5-bef7-d871b541c019",
|
|
}
|
|
metadata:
|
|
type: object
|
|
description: Journal payload.
|
|
example: { "Update": "Calvo-Felkins" }
|
|
xml:
|
|
name: journal
|
|
|
|
JournalPage:
|
|
type: object
|
|
properties:
|
|
journals:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: "#/components/schemas/Journal"
|
|
total:
|
|
type: integer
|
|
example: 1
|
|
description: Total number of items.
|
|
offset:
|
|
type: integer
|
|
description: Number of items to skip during retrieval.
|
|
limit:
|
|
type: integer
|
|
example: 10
|
|
description: Maximum number of items to return in one page.
|
|
required:
|
|
- journals
|
|
- total
|
|
- offset
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
example: { "error": "malformed entity specification" }
|
|
|
|
parameters:
|
|
domain_id:
|
|
name: domainID
|
|
description: Unique identifier for a domain.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
client_id:
|
|
name: clientID
|
|
description: Unique identifier for a client
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
entity_type:
|
|
name: entityType
|
|
description: Type of entity, e.g. group, client, channel.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- group
|
|
- client
|
|
- channel
|
|
required: true
|
|
example: group
|
|
|
|
user_id:
|
|
name: userID
|
|
description: Unique identifier for a user.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
id:
|
|
name: id
|
|
description: Unique identifier for an entity, e.g. group, channel or client. Used together with entity_type.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
offset:
|
|
name: offset
|
|
description: Number of items to skip during retrieval.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
required: false
|
|
example: 0
|
|
|
|
limit:
|
|
name: limit
|
|
description: Size of the subset to retrieve.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 10
|
|
maximum: 100
|
|
minimum: 1
|
|
required: false
|
|
example: 10
|
|
|
|
operation:
|
|
name: operation
|
|
description: Journal operation.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
example: user.create
|
|
|
|
with_attributes:
|
|
name: with_attributes
|
|
description: Include journal attributes.
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
required: false
|
|
example: true
|
|
|
|
with_metadata:
|
|
name: with_metadata
|
|
description: Include journal metadata.
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
required: false
|
|
example: true
|
|
|
|
from:
|
|
name: from
|
|
description: Start date in unix time.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
example: 1966777289
|
|
|
|
to:
|
|
name: to
|
|
description: End date in unix time.
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
example: 1966777289
|
|
|
|
dir:
|
|
name: dir
|
|
description: Sort direction.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- asc
|
|
- desc
|
|
required: false
|
|
example: desc
|
|
|
|
responses:
|
|
JournalsPageRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JournalPage"
|
|
|
|
HealthRes:
|
|
description: Service Health Check.
|
|
content:
|
|
application/health+json:
|
|
schema:
|
|
$ref: "./schemas/health_info.yaml"
|
|
|
|
ServiceError:
|
|
description: Unexpected server-side error occurred.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
* User access: "Authorization: Bearer <user_access_token>"
|
|
|
|
security:
|
|
- bearerAuth: []
|