From 45d70ca34d7ff00dfa4afcdeb530227c1f2d8e79 Mon Sep 17 00:00:00 2001 From: dborovcanin Date: Tue, 31 Dec 2024 10:04:35 +0000 Subject: [PATCH] deploy: 3bbb25bd64fd654435cbde929006b6bf61cc837b --- apis/api/openapi/auth.yml | 833 ----------- apis/api/openapi/certs.yml | 313 ---- apis/api/openapi/http.yml | 182 --- apis/api/openapi/invitations.yml | 537 ------- apis/api/openapi/journal.yml | 344 ----- apis/api/openapi/provision.yml | 129 -- apis/api/openapi/things.yml | 2067 -------------------------- apis/api/openapi/twins.yml | 431 ------ apis/api/openapi/users.yml | 2312 ------------------------------ swagger-config.json | 2 +- 10 files changed, 1 insertion(+), 7149 deletions(-) delete mode 100644 apis/api/openapi/auth.yml delete mode 100644 apis/api/openapi/certs.yml delete mode 100644 apis/api/openapi/http.yml delete mode 100644 apis/api/openapi/invitations.yml delete mode 100644 apis/api/openapi/journal.yml delete mode 100644 apis/api/openapi/provision.yml delete mode 100644 apis/api/openapi/things.yml delete mode 100644 apis/api/openapi/twins.yml delete mode 100644 apis/api/openapi/users.yml diff --git a/apis/api/openapi/auth.yml b/apis/api/openapi/auth.yml deleted file mode 100644 index fde5df18e..000000000 --- a/apis/api/openapi/auth.yml +++ /dev/null @@ -1,833 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.3 -info: - title: Magistrala Auth Service - description: | - This is the Auth Server based on the OpenAPI 3.0 specification. It is the HTTP API for managing platform users. 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@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:8189 - - url: https://localhost:8189 - -tags: - - name: Keys - description: Everything about your Keys. - externalDocs: - description: Find out more about keys - url: https://docs.magistrala.abstractmachines.fr/ - - - name: Domains - description: Everything about your Domains. - externalDocs: - description: Find out more about domains - url: https://docs.magistrala.abstractmachines.fr/ - - - name: Health - description: Service health check endpoint. - externalDocs: - description: Find out more about health check - url: https://docs.magistrala.abstractmachines.fr/ - - -paths: - /domains: - post: - tags: - - Domains - summary: Adds new domain - description: | - Adds new domain. - requestBody: - $ref: "#/components/requestBodies/DomainCreateReq" - responses: - "201": - $ref: "#/components/responses/DomainCreateRes" - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "409": - description: Failed due to using an existing alias. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - get: - summary: Retrieves list of domains. - description: | - Retrieves list of domains that the user have access. - parameters: - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - - $ref: "#/components/parameters/DomainName" - - $ref: "#/components/parameters/Permission" - tags: - - Domains - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/DomainsPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}: - get: - summary: Retrieves domain information - description: | - Retrieves a specific domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/DomainRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - patch: - summary: Updates name, metadata, tags and alias of the domain. - description: | - Updates name, metadata, tags and alias of the domain. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/DomainUpdateReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/DomainRes" - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access to domain id. - "404": - description: Failed due to non existing domain. - "415": - description: Missing or invalid content type. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}/permissions: - get: - summary: Retrieves user permissions on domain. - description: | - Retrieves user permissions on domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/DomainPermissionRes" - "400": - description: Malformed entity specification. - "401": - description: Missing or invalid access token provided. - "403": - description: Failed authorization over the domain. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - /domains/{domainID}/enable: - post: - summary: Enables a domain - description: | - Enables a specific domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - security: - - bearerAuth: [] - responses: - "200": - description: Successfully enabled domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}/disable: - post: - summary: Disable a domain - description: | - Disable a specific domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - security: - - bearerAuth: [] - responses: - "200": - description: Successfully disabled domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}/freeze: - post: - summary: Freeze a domain - description: | - Freeze a specific domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - security: - - bearerAuth: [] - responses: - "200": - description: Successfully freezed domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}/users/assign: - post: - summary: Assign users to domain - description: | - Assign users to domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/AssignUserReq" - security: - - bearerAuth: [] - responses: - "200": - description: Users successfully assigned to domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "409": - description: Conflict of data. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /domains/{domainID}/users/unassign: - post: - summary: Unassign user from domain - description: | - Unassign user from domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/UnassignUsersReq" - security: - - bearerAuth: [] - responses: - "204": - description: Users successfully unassigned from domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "409": - description: Conflict of data. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - /keys: - post: - operationId: issueKey - tags: - - Keys - summary: Issue API key - description: | - Generates a new API key. Thew new API key will - be uniquely identified by its ID. - requestBody: - $ref: "#/components/requestBodies/KeyRequest" - responses: - "201": - description: Issued new key. - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "409": - description: Failed due to using already existing ID. - "415": - description: Missing or invalid content type. - "500": - $ref: "#/components/responses/ServiceError" - - /keys/{keyID}: - get: - operationId: getKey - summary: Gets API key details. - description: | - Gets API key details for the given key. - tags: - - Keys - parameters: - - $ref: "#/components/parameters/ApiKeyId" - responses: - "200": - $ref: "#/components/responses/KeyRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - delete: - operationId: revokeKey - summary: Revoke API key - description: | - Revoke API key identified by the given ID. - tags: - - Keys - parameters: - - $ref: "#/components/parameters/ApiKeyId" - responses: - "204": - description: Key revoked. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/domains: - get: - tags: - - Domains - summary: Lists domains associated with a user. - description: | - Retrieves a list of domains associated with a user. 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: "users.yml#/components/parameters/UserID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/DomainsPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: | - Missing or invalid access token provided. - This endpoint is available only for administrators. - "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: - DomainReqObj: - type: object - properties: - name: - type: string - example: domainName - description: Domain name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: domain tags. - metadata: - type: object - example: { "domain": "example.com" } - description: Arbitrary, object-encoded domain's data. - alias: - type: string - example: domain alias - description: Domain alias. - required: - - name - - alias - Domain: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Domain unique identifier. - name: - type: string - example: domainName - description: Domain name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: domain tags. - metadata: - type: object - example: { "domain": "example.com" } - description: Arbitrary, object-encoded domain's data. - alias: - type: string - example: domain alias - description: Domain alias. - status: - type: string - description: Domain Status - format: string - example: enabled - created_by: - type: string - format: uuid - example: "0d837f56-3f8a-4e2a-9359-6347d0fc9f06 " - description: User ID of the user who created the domain. - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the domain was created. - updated_by: - type: string - format: uuid - example: "80f66b77-ed74-4e74-9f88-6cce9a0a3049" - description: User ID of the user who last updated the domain. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the domain was last updated. - xml: - name: domain - - DomainsPage: - type: object - properties: - domains: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Domain" - 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: - - domains - - total - - offset - DomainUpdate: - type: object - properties: - name: - type: string - example: domainName - description: Domain name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: domain tags. - metadata: - type: object - example: { "domain": "example.com" } - description: Arbitrary, object-encoded thing's data. - alias: - type: string - example: domain alias - description: Domain alias. - Permissions: - type: object - properties: - permissions: - type: array - minItems: 0 - items: - type: string - description: Permissions - - AssignUserDomainRelationReq: - type: object - properties: - user_ids: - type: array - minItems: 1 - items: - type: string - description: Users IDs - example: - [ - "5dc1ce4b-7cc9-4f12-98a6-9d74cc4980bb", - "c01ed106-e52d-4aa4-bed3-39f360177cfa", - ] - relation: - type: string - enum: ["administrator", "editor", "contributor", "member", "guest"] - example: "administrator" - description: Policy relations. - required: - - user_ids - - relation - UnassignUserDomainRelationReq: - type: object - properties: - user_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - required: - - user_id - Key: - type: object - properties: - id: - type: string - format: uuid - example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945" - description: API key unique identifier - issuer_id: - type: string - format: uuid - example: "9118de62-c680-46b7-ad0a-21748a52833a" - description: In ID of the entity that issued the token. - type: - type: integer - example: 0 - description: API key type. Keys of different type are processed differently. - subject: - type: string - format: string - example: "test@example.com" - description: User's email or service identifier of API key subject. - issued_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the key is generated. - expires_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the Key expires. If this field is missing, - that means that Key is valid indefinitely. - - parameters: - DomainID: - name: domainID - description: Unique domain identifier. - in: path - schema: - type: string - format: uuid - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - Status: - name: status - description: Domain status. - in: query - schema: - type: string - default: enabled - required: false - example: enabled - DomainName: - name: name - description: Domain's name. - in: query - schema: - type: string - required: false - example: "domainName" - Permission: - name: permission - description: permission. - in: query - schema: - type: string - required: false - example: "edit" - ApiKeyId: - name: keyID - description: API Key ID. - 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 - Metadata: - name: metadata - description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json. - in: query - required: false - schema: - type: object - additionalProperties: {} - Type: - name: type - description: The type of the API Key. - in: query - schema: - type: integer - default: 0 - minimum: 0 - required: false - Subject: - name: subject - description: The subject of an API Key - in: query - schema: - type: string - required: false - - requestBodies: - DomainCreateReq: - description: JSON-formatted document describing the new domain to be registered - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/DomainReqObj" - DomainUpdateReq: - description: JSON-formated document describing the name, alias, tags, and metadata of the domain to be updated - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/DomainUpdate" - AssignUserReq: - description: JSON-formated document describing the policy related to assigning users to a domain - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignUserDomainRelationReq" - - UnassignUsersReq: - description: JSON-formated document describing the policy related to unassigning user from a domain - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UnassignUserDomainRelationReq" - - KeyRequest: - description: JSON-formatted document describing key request. - required: true - content: - application/json: - schema: - type: object - properties: - type: - type: integer - example: 0 - description: API key type. Keys of different type are processed differently. - duration: - type: number - format: integer - example: 23456 - description: Number of seconds issued token is valid for. - - responses: - ServiceError: - description: Unexpected server-side error occurred. - - DomainCreateRes: - description: Create new domain. - headers: - Location: - schema: - type: string - format: url - description: Registered domain relative URL in the format `/domains/` - content: - application/json: - schema: - $ref: "#/components/schemas/Domain" - - DomainRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Domain" - DomainPermissionRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Permissions" - DomainsPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/DomainsPage" - - KeyRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Key" - links: - revoke: - operationId: revokeKey - parameters: - keyID: $response.body#/id - - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "./schemas/HealthInfo.yml" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * Users access: "Authorization: Bearer " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/certs.yml b/apis/api/openapi/certs.yml deleted file mode 100644 index b5ced9377..000000000 --- a/apis/api/openapi/certs.yml +++ /dev/null @@ -1,313 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.1 -info: - title: Magistrala Certs service - description: | - HTTP API for Certs service - Some useful links: - - [The Magistrala repository](https://github.com/absmach/magistrala) - contact: - email: info@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9019 - - url: https://localhost:9019 - -tags: - - name: certs - description: Everything about your Certs - externalDocs: - description: Find out more about certs - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /{domainID}/certs: - post: - operationId: createCert - summary: Creates a certificate for thing - description: Creates a certificate for thing - tags: - - certs - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/CertReq" - responses: - "201": - description: Created - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "403": - description: Failed to perform authorization over the entity. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - /{domainID}/certs/{certID}: - get: - operationId: getCert - summary: Retrieves a certificate - description: | - Retrieves a certificate for a given cert ID. - tags: - - certs - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/CertID" - responses: - "200": - $ref: "#/components/responses/CertRes" - "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: | - Failed to retrieve corresponding certificate. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - delete: - operationId: revokeCert - summary: Revokes a certificate - description: | - Revokes a certificate for a given cert ID. - tags: - - certs - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/CertID" - responses: - "200": - $ref: "#/components/responses/RevokeRes" - "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: | - Failed to revoke corresponding certificate. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - /{domainID}/serials/{thingID}: - get: - operationId: getSerials - summary: Retrieves certificates' serial IDs - description: | - Retrieves a list of certificates' serial IDs for a given thing ID. - tags: - - certs - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - responses: - "200": - $ref: "#/components/responses/SerialsPageRes" - "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: | - Failed to retrieve corresponding certificates. - "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: - parameters: - ThingID: - name: thingID - description: Thing ID - in: path - schema: - type: string - format: uuid - required: true - CertID: - name: certID - description: Serial of certificate - in: path - schema: - type: string - format: uuid - required: true - - schemas: - Cert: - type: object - properties: - thing_id: - type: string - format: uuid - description: Corresponding Magistrala Thing ID. - client_cert: - type: string - description: Client Certificate. - client_key: - type: string - description: Key for the client_cert. - issuing_ca: - type: string - description: CA Certificate that is used to issue client certs, usually intermediate. - serial: - type: string - description: Certificate serial - expire: - type: string - description: Certificate expiry date - Serial: - type: object - properties: - serial: - type: string - description: Certificate serial - CertsPage: - type: object - properties: - certs: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Cert" - 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. - SerialsPage: - type: object - properties: - serials: - type: array - description: Certificate serials IDs. - minItems: 0 - uniqueItems: true - items: - type: string - 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. - Revoke: - type: object - properties: - revocation_time: - type: string - description: Certificate revocation time - - requestBodies: - CertReq: - description: | - Issues a certificate that is required for mTLS. To create a certificate for a thing - provide a thing id, data identifying particular thing will be embedded into the Certificate. - x509 and ECC certificates are supported when using when Vault is used as PKI. - content: - application/json: - schema: - type: object - required: - - thing_id - - ttl - properties: - thing_id: - type: string - format: uuid - ttl: - type: string - example: "10h" - - responses: - ServiceError: - description: Unexpected server-side error occurred. - CertRes: - description: Certificate data. - content: - application/json: - schema: - $ref: "#/components/schemas/Cert" - links: - serial: - operationId: getSerials - parameters: - thingID: $response.body#/thing_id - delete: - operationId: revokeCert - parameters: - certID: $response.body#/serial - CertsPageRes: - description: Certificates page. - content: - application/json: - schema: - $ref: "#/components/schemas/CertsPage" - SerialsPageRes: - description: Serials page. - content: - application/json: - schema: - $ref: "#/components/schemas/SerialsPage" - RevokeRes: - description: Certificate revoked. - content: - application/json: - schema: - $ref: "#/components/schemas/Revoke" - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "./schemas/HealthInfo.yml" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * Users access: "Authorization: Bearer " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/http.yml b/apis/api/openapi/http.yml deleted file mode 100644 index f366458bd..000000000 --- a/apis/api/openapi/http.yml +++ /dev/null @@ -1,182 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.1 -info: - title: Magistrala http adapter - description: | - HTTP API for sending messages through communication channels. - Some useful links: - - [The Magistrala repository](https://github.com/absmach/magistrala) - contact: - email: info@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:8008 - - url: https://localhost:8008 - -tags: - - name: messages - description: Everything about your Messages - externalDocs: - description: Find out more about messages - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /channels/{id}/messages: - post: - summary: Sends message to the communication channel - description: | - Sends message to the communication channel. Messages can be sent as - JSON formatted SenML or as blob. - tags: - - messages - parameters: - - $ref: "#/components/parameters/ID" - requestBody: - $ref: "#/components/requestBodies/MessageReq" - responses: - "202": - description: Message is accepted for processing. - "400": - description: Message discarded due to its malformed content. - "401": - description: Missing or invalid access token provided. - "404": - description: Message discarded due to invalid channel id. - "415": - description: Message discarded due to invalid or missing content type. - "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: - SenMLRecord: - type: object - properties: - bn: - type: string - description: Base Name - bt: - type: number - format: double - description: Base Time - bu: - type: number - format: double - description: Base Unit - bv: - type: number - format: double - description: Base Value - bs: - type: number - format: double - description: Base Sum - bver: - type: number - format: double - description: Version - n: - type: string - description: Name - u: - type: string - description: Unit - v: - type: number - format: double - description: Value - vs: - type: string - description: String Value - vb: - type: boolean - description: Boolean Value - vd: - type: string - description: Data Value - s: - type: number - format: double - description: Value Sum - t: - type: number - format: double - description: Time - ut: - type: number - format: double - description: Update Time - SenMLArray: - type: array - items: - $ref: "#/components/schemas/SenMLRecord" - - parameters: - ID: - name: id - description: Unique channel identifier. - in: path - schema: - type: string - format: uuid - required: true - - requestBodies: - MessageReq: - description: | - Message to be distributed. Since the platform expects messages to be - properly formatted SenML in order to be post-processed, clients are - obliged to specify Content-Type header for each published message. - Note that all messages that aren't SenML will be accepted and published, - but no post-processing will be applied. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/SenMLArray" - - responses: - ServiceError: - description: Unexpected server-side error occurred. - - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "./schemas/HealthInfo.yml" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: uuid - description: | - * Thing access: "Authorization: Thing " - - basicAuth: - type: http - scheme: basic - description: | - * Things access: "Authorization: Basic " - -security: - - bearerAuth: [] - - basicAuth: [] diff --git a/apis/api/openapi/invitations.yml b/apis/api/openapi/invitations.yml deleted file mode 100644 index 541e36859..000000000 --- a/apis/api/openapi/invitations.yml +++ /dev/null @@ -1,537 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.3 -info: - title: Magistrala Invitations Service - description: | - This is the Invitations Server based on the OpenAPI 3.0 specification. It is the HTTP API for managing platform invitations. 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@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9020 - - url: https://localhost:9020 - -tags: - - name: Invitations - description: Everything about your Invitations - externalDocs: - description: Find out more about Invitations - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /invitations: - post: - operationId: sendInvitation - tags: - - Invitations - summary: Send invitation - description: | - Send invitation to user to join domain. - requestBody: - $ref: "#/components/requestBodies/SendInvitationReq" - security: - - bearerAuth: [] - responses: - "201": - description: Invitation sent. - "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. - "500": - $ref: "#/components/responses/ServiceError" - - get: - operationId: listInvitations - tags: - - Invitations - summary: List invitations - description: | - Retrieves a list of invitations. 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/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/UserID" - - $ref: "#/components/parameters/InvitedBy" - - $ref: "#/components/parameters/DomainID" - - $ref: "#/components/parameters/Relation" - - $ref: "#/components/parameters/State" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/InvitationPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: | - Missing or invalid access token provided. - This endpoint is available only for administrators. - "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" - - /invitations/accept: - post: - operationId: acceptInvitation - summary: Accept invitation - description: | - Current logged in user accepts invitation to join domain. - tags: - - Invitations - security: - - bearerAuth: [] - requestBody: - $ref: "#/components/requestBodies/AcceptInvitationReq" - responses: - "204": - description: Invitation accepted. - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - /invitations/reject: - post: - operationId: rejectInvitation - summary: Reject invitation - description: | - Current logged in user rejects invitation to join domain. - tags: - - Invitations - security: - - bearerAuth: [] - requestBody: - $ref: "#/components/requestBodies/AcceptInvitationReq" - responses: - "204": - description: Invitation rejected. - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - /invitations/{user_id}/{domain_id}: - get: - operationId: getInvitation - summary: Retrieves a specific invitation - description: | - Retrieves a specific invitation that is identifier by the user ID and domain ID. - tags: - - Invitations - parameters: - - $ref: "#/components/parameters/user_id" - - $ref: "#/components/parameters/domain_id" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/InvitationRes" - "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" - - delete: - operationId: deleteInvitation - summary: Deletes a specific invitation - description: | - Deletes a specific invitation that is identifier by the user ID and domain ID. - tags: - - Invitations - parameters: - - $ref: "#/components/parameters/user_id" - - $ref: "#/components/parameters/domain_id" - security: - - bearerAuth: [] - responses: - "204": - description: Invitation deleted. - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "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: - SendInvitationReqObj: - type: object - properties: - user_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Domain unique identifier. - relation: - type: string - enum: - - administrator - - editor - - contributor - - member - - guest - - domain - - parent_group - - role_group - - group - - platform - example: editor - description: Relation between user and domain. - resend: - type: boolean - example: true - description: Resend invitation. - required: - - user_id - - domain_id - - relation - - Invitation: - type: object - properties: - invited_by: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - user_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Domain unique identifier. - relation: - type: string - enum: - - administrator - - editor - - contributor - - member - - guest - - domain - - parent_group - - role_group - - group - - platform - example: editor - description: Relation between user and domain. - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - confirmed_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - xml: - name: invitation - - InvitationPage: - type: object - properties: - invitations: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Invitation" - 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: - - invitations - - total - - offset - - Error: - type: object - properties: - error: - type: string - description: Error message - example: { "error": "malformed entity specification" } - - HealthRes: - type: object - properties: - status: - type: string - description: Service status. - enum: - - pass - version: - type: string - description: Service version. - example: 0.14.0 - commit: - type: string - description: Service commit hash. - example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62 - description: - type: string - description: Service description. - example: service - build_time: - type: string - description: Service build time. - example: 1970-01-01_00:00:00 - - parameters: - 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: 10 - minimum: 1 - required: false - example: "10" - - UserID: - name: user_id - description: Unique user identifier. - in: query - schema: - type: string - format: uuid - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - user_id: - name: user_id - description: Unique user identifier. - in: path - schema: - type: string - format: uuid - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - DomainID: - name: domain_id - description: Unique identifier for a domain. - in: query - schema: - type: string - format: uuid - required: false - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - domain_id: - name: domain_id - description: Unique identifier for a domain. - in: path - schema: - type: string - format: uuid - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - InvitedBy: - name: invited_by - description: Unique identifier for a user that invited the user. - in: query - schema: - type: string - format: uuid - required: false - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - Relation: - name: relation - description: Relation between user and domain. - in: query - schema: - type: string - enum: - - administrator - - editor - - contributor - - member - - guest - - domain - - parent_group - - role_group - - group - - platform - required: false - example: editor - - State: - name: state - description: Invitation state. - in: query - schema: - type: string - enum: - - pending - - accepted - - all - required: false - example: accepted - - requestBodies: - SendInvitationReq: - description: JSON-formatted document describing request for sending invitation - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/SendInvitationReqObj" - - AcceptInvitationReq: - description: JSON-formatted document describing request for accepting invitation - required: true - content: - application/json: - schema: - type: object - properties: - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Domain unique identifier. - required: - - domain_id - - responses: - InvitationRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Invitation" - links: - delete: - operationId: deleteInvitation - parameters: - user_id: $response.body#/user_id - domain_id: $response.body#/domain_id - - InvitationPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/InvitationPage" - - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "#/components/schemas/HealthRes" - - 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 " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/journal.yml b/apis/api/openapi/journal.yml deleted file mode 100644 index 9cea4a1f1..000000000 --- a/apis/api/openapi/journal.yml +++ /dev/null @@ -1,344 +0,0 @@ -# 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/master/LICENSE - version: 0.14.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/{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: - 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 - - entity_type: - name: entityType - description: Type of entity, e.g. user, group, thing, etc.entityType - in: path - schema: - type: string - enum: - - group - - thing - - 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 thing. 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: 10 - 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: string - format: int64 - required: false - example: 1966777289 - - to: - name: to - description: End date in unix time. - in: query - schema: - type: string - 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/HealthInfo.yml" - - 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 " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/provision.yml b/apis/api/openapi/provision.yml deleted file mode 100644 index 9b814e8bc..000000000 --- a/apis/api/openapi/provision.yml +++ /dev/null @@ -1,129 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.1 -info: - title: Magistrala Provision service - description: | - HTTP API for Provision service - Some useful links: - - [The Magistrala repository](https://github.com/absmach/magistrala) - contact: - email: info@abstracmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9016 - - url: https://localhost:9016 - -tags: - - name: provision - description: Everything about your Provision - externalDocs: - description: Find out more about provision - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /{domainID}/mapping: - post: - summary: Adds new device to proxy - description: Adds new device to proxy - tags: - - provision - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/ProvisionReq" - responses: - "201": - description: Created - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - get: - summary: Gets current mapping. - description: Gets current mapping. This can be used in UI - so that when bootstrap config is created from UI matches - configuration created with provision service. - tags: - - provision - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - responses: - "200": - $ref: "#/components/responses/ProvisionRes" - "401": - description: Missing or invalid access token provided. - "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: - requestBodies: - ProvisionReq: - description: MAC address of device or other identifier - content: - application/json: - schema: - type: object - required: - - external_id - - external_key - properties: - external_id: - type: string - external_key: - type: string - name: - type: string - - responses: - ServiceError: - description: Unexpected server-side error occurred. - ProvisionRes: - description: Current mapping JSON representation. - content: - application/json: - schema: - type: object - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "./schemas/HealthInfo.yml" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * Users access: "Authorization: Bearer " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/things.yml b/apis/api/openapi/things.yml deleted file mode 100644 index 4550ef461..000000000 --- a/apis/api/openapi/things.yml +++ /dev/null @@ -1,2067 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.3 -info: - title: Magistrala Things Service - description: | - This is the Things Server based on the OpenAPI 3.0 specification. It is the HTTP API for managing platform things and channels. 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@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9000 - - url: https://localhost:9000 - -tags: - - name: Things - description: Everything about your Things - externalDocs: - description: Find out more about things - url: https://docs.magistrala.abstractmachines.fr/ - - name: Channels - description: Everything about your Channels - externalDocs: - description: Find out more about things channels - url: https://docs.magistrala.abstractmachines.fr/ - - name: Policies - description: Access to things policies - externalDocs: - description: Find out more about things policies - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /{domainID}/things: - post: - operationId: createThing - tags: - - Things - summary: Adds new thing - description: | - Adds new thing to the list of things owned by user identified using - the provided access token. - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/ThingCreateReq" - responses: - "201": - $ref: "#/components/responses/ThingCreateRes" - "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" - - get: - operationId: listThings - tags: - - Things - summary: Retrieves things - description: | - Retrieves a list of things. Due to performance concerns, data - is retrieved in subsets. The API things 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: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - - $ref: "#/components/parameters/ThingName" - - $ref: "#/components/parameters/Tags" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingPageRes" - "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}/things/bulk: - post: - operationId: bulkCreateThings - summary: Bulk provisions new things - description: | - Adds new things to the list of things owned by user identified using - the provided access token. - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - tags: - - Things - requestBody: - $ref: "#/components/requestBodies/ThingsCreateReq" - responses: - "200": - $ref: "#/components/responses/ThingPageRes" - "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. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}: - get: - operationId: getThing - summary: Retrieves thing info - description: | - Retrieves a specific thing that is identifier by the thing ID. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "400": - description: Failed due to malformed domain 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" - - patch: - operationId: updateThing - summary: Updates name and metadata of the thing. - description: | - Update is performed by replacing the current resource data with values - provided in a request payload. Note that the thing's type and ID - cannot be changed. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - requestBody: - $ref: "#/components/requestBodies/ThingUpdateReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "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: Failed due to non existing thing. - "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" - delete: - summary: Delete thing for a thing with the given id. - description: | - Delete thing removes a thing with the given id from repo - and removes all the policies related to this thing. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - security: - - bearerAuth: [] - responses: - "204": - description: Thing deleted. - "400": - description: Failed due to malformed domain ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access to thing id. - "404": - description: Missing thing. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}/tags: - patch: - operationId: updateThingTags - summary: Updates tags the thing. - description: | - Updates tags of the thing with provided ID. Tags is updated using - authorization token and the new tags received in request. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - requestBody: - $ref: "#/components/requestBodies/ThingUpdateTagsReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing thing. - "401": - description: Missing or invalid access token provided. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}/secret: - patch: - operationId: updateThingSecret - summary: Updates secret of the identified thing. - description: | - Updates secret of the identified in thing. Secret is updated using - authorization token and the new received info. Update is performed by replacing current key with a new one. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - requestBody: - $ref: "#/components/requestBodies/ThingUpdateSecretReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "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: Failed due to non existing thing. - "409": - description: Specified key already exists. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}/disable: - post: - operationId: disableThing - summary: Disables a thing - description: | - Disables a specific thing that is identifier by the thing ID. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "400": - description: Failed due to malformed thing's 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. - "409": - description: Failed due to already disabled thing. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}/enable: - post: - operationId: enableThing - summary: Enables a thing - description: | - Enables a specific thing that is identifier by the thing ID. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ThingRes" - "400": - description: Failed due to malformed thing's 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. - "409": - description: Failed due to already enabled thing. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/things/{thingID}/share: - post: - operationId: shareThing - summary: Shares a thing - description: | - Shares a specific thing that is identified by the thing ID. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - requestBody: - $ref: "#/components/requestBodies/ShareThingReq" - security: - - bearerAuth: [] - responses: - "200": - description: Thing shared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/things/{thingID}/unshare: - post: - operationId: unshareThing - summary: Unshares a thing - description: | - Unshares a specific thing that is identified by the thing ID. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - requestBody: - $ref: "#/components/requestBodies/ShareThingReq" - security: - - bearerAuth: [] - responses: - "200": - description: Thing unshared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/channels/{chanID}/things: - get: - operationId: listThingsInaChannel - summary: List of things connected to specified channel - description: | - Retrieves list of things connected to specified channel with pagination - metadata. - tags: - - Things - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Connected" - responses: - "200": - $ref: "#/components/responses/ThingsPageRes" - "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}/channels: - post: - operationId: createChannel - tags: - - Channels - summary: Creates new channel - description: | - Creates new channel in domain. - requestBody: - $ref: "#/components/requestBodies/ChannelCreateReq" - security: - - bearerAuth: [] - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - responses: - "201": - $ref: "#/components/responses/ChannelCreateRes" - "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" - - get: - operationId: listChannels - summary: Lists channels. - description: | - Retrieves a list of channels. Due to performance concerns, data - is retrieved in subsets. The API things must ensure that the entire - dataset is consumed either by making subsequent requests, or by - increasing the subset size of the initial request. - tags: - - Channels - security: - - bearerAuth: [] - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/ChannelName" - responses: - "200": - $ref: "#/components/responses/ChannelPageRes" - "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: Channel does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{chanID}: - get: - operationId: getChannel - summary: Retrieves channel info. - description: | - Gets info on a channel specified by id. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ChannelRes" - "400": - description: Failed due to malformed channel's or domain ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Channel does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - put: - operationId: updateChannel - summary: Updates channel data. - description: | - Update is performed by replacing the current resource data with values - provided in a request payload. Note that the channel's ID will not be - affected. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - security: - - bearerAuth: [] - requestBody: - $ref: "#/components/requestBodies/ChannelUpdateReq" - responses: - "200": - $ref: "#/components/responses/ChannelRes" - "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: Channel does not exist. - "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" - delete: - summary: Delete channel for given channel id. - description: | - Delete channel remove given channel id from repo - and removes all the policies related to channel. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - security: - - bearerAuth: [] - responses: - "204": - description: Channel deleted. - "400": - description: Failed due to malformed domain ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access to thing id. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{chanID}/enable: - post: - operationId: enableChannel - summary: Enables a channel - description: | - Enables a specific channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ChannelRes" - "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. - "409": - description: Failed due to already enabled channel. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{chanID}/disable: - post: - operationId: disableChannel - summary: Disables a channel - description: | - Disables a specific channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/ChannelRes" - "400": - description: Failed due to malformed channel's 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. - "409": - description: Failed due to already disabled channel. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{chanID}/users/assign: - post: - operationId: assignUsersToChannel - summary: Assigns a member to a channel - description: | - Assigns a specific member to a channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - requestBody: - $ref: "#/components/requestBodies/AssignUserReq" - security: - - bearerAuth: [] - responses: - "200": - description: Thing shared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/channels/{chanID}/users/unassign: - post: - operationId: unassignUsersFromChannel - summary: Unassigns a member from a channel - description: | - Unassigns a specific member from a channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - requestBody: - $ref: "#/components/requestBodies/AssignUserReq" - security: - - bearerAuth: [] - responses: - "204": - description: Thing unshared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/channels/{chanID}/groups/assign: - post: - operationId: assignGroupsToChannel - summary: Assigns a member to a channel - description: | - Assigns a specific member to a channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - requestBody: - $ref: "#/components/requestBodies/AssignUsersReq" - security: - - bearerAuth: [] - responses: - "200": - description: Thing shared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/channels/{chanID}/groups/unassign: - post: - operationId: unassignGroupsFromChannel - summary: Unassigns a member from a channel - description: | - Unassigns a specific member from a channel that is identifier by the channel ID. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - requestBody: - $ref: "#/components/requestBodies/AssignUsersReq" - security: - - bearerAuth: [] - responses: - "204": - description: Thing unshared. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/things/{thingID}/channels: - get: - operationId: listChannelsConnectedToThing - summary: List of channels connected to specified thing - description: | - Retrieves list of channels connected to specified thing with pagination - metadata. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ThingID" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - responses: - "200": - $ref: "#/components/responses/ChannelPageRes" - "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: Thing does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/users/{memberID}/channels: - get: - operationId: listChannelsConnectedToUser - summary: List of channels connected to specified user - description: | - Retrieves list of channels connected to specified user with pagination - metadata. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/MemberID" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - responses: - "200": - $ref: "#/components/responses/ChannelPageRes" - "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: Thing does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{memberID}/channels: - get: - operationId: listChannelsConnectedToGroup - summary: List of channels connected to specified group - description: | - Retrieves list of channels connected to specified group with pagination - metadata. - tags: - - Channels - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/MemberID" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - responses: - "200": - $ref: "#/components/responses/ChannelPageRes" - "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: Thing does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/connect: - post: - operationId: connectThingsAndChannels - summary: Connects thing and channel. - description: | - Connect things specified by IDs to channels specified by IDs. - Channel and thing are owned by user identified using the provided access token. - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - tags: - - Policies - requestBody: - $ref: "#/components/requestBodies/ConnCreateReq" - responses: - "201": - $ref: "#/components/responses/ConnCreateRes" - "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: Entity already exist. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/disconnect: - post: - operationId: disconnectThingsAndChannels - summary: Disconnect things and channels using lists of IDs. - description: | - Disconnect things from channels specified by lists of IDs. - Channels and things are owned by user identified using the provided access token. - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - tags: - - Policies - requestBody: - $ref: "#/components/requestBodies/DisconnReq" - responses: - "204": - $ref: "#/components/responses/DisconnRes" - "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. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{chanID}/things/{thingID}/connect: - post: - operationId: connectThingToChannel - summary: Connects a thing to a channel - description: | - Connects a specific thing to a channel that is identifier by the channel ID. - tags: - - Policies - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - - $ref: "#/components/parameters/ThingID" - responses: - "200": - description: Thing connected. - "400": - description: Failed due to malformed thing's 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" - - /{domainID}/channels/{chanID}/things/{thingID}/disconnect: - post: - operationId: disconnectThingFromChannel - summary: Disconnects a thing to a channel - description: | - Disconnects a specific thing to a channel that is identifier by the channel ID. - tags: - - Policies - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/chanID" - - $ref: "#/components/parameters/ThingID" - responses: - "200": - description: Thing connected. - "400": - description: Failed due to malformed thing's 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" - - /health: - get: - summary: Retrieves service health check info. - tags: - - health - security: [] - responses: - "200": - $ref: "#/components/responses/HealthRes" - "500": - $ref: "#/components/responses/ServiceError" - -components: - schemas: - ThingReqObj: - type: object - properties: - name: - type: string - example: thingName - description: Thing name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: Thing tags. - credentials: - type: object - properties: - identity: - type: string - example: "thingidentity" - description: Thing's identity will be used as its unique identifier - secret: - type: string - format: password - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - minimum: 8 - description: Free-form account secret used for acquiring auth token(s). - metadata: - type: object - example: { "model": "example" } - description: Arbitrary, object-encoded thing's data. - status: - type: string - description: Thing Status - format: string - example: enabled - required: - - credentials - - ChannelReqObj: - type: object - properties: - name: - type: string - example: channelName - description: Free-form channel name. Channel name is unique on the given hierarchy level. - description: - type: string - example: long channel description - description: Channel description, free form text. - parent_id: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Id of parent channel, it must be existing channel. - metadata: - type: object - example: { "location": "example" } - description: Arbitrary, object-encoded channels's data. - status: - type: string - description: Channel Status - format: string - example: enabled - required: - - name - - PolicyReqObj: - type: object - properties: - user_ids: - type: array - minItems: 0 - items: - type: string - description: User IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - relation: - type: string - example: "editor" - description: Policy relation. - required: - - user_ids - - relation - - AssignReqObj: - type: object - properties: - members: - type: array - minItems: 0 - items: - type: string - description: Members IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - relation: - type: string - example: "editor" - description: Policy relations. - member_kind: - type: string - example: "user" - description: Member kind. - required: - - members - - relation - - member_kind - - AssignUserReqObj: - type: object - properties: - users_ids: - type: array - minItems: 0 - items: - type: string - description: Users IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - relation: - type: string - example: "editor" - description: Policy relations. - required: - - users_ids - - relation - - AssignUsersReqObj: - type: object - properties: - group_ids: - type: array - minItems: 0 - items: - type: string - description: Group IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - required: - - group_ids - - Thing: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Thing unique identifier. - name: - type: string - example: thingName - description: Thing name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: Thing tags. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: ID of the domain to which thing belongs. - credentials: - type: object - properties: - identity: - type: string - example: thingidentity - description: Thing Identity for example email address. - secret: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Thing secret password. - metadata: - type: object - example: { "model": "example" } - description: Arbitrary, object-encoded thing's data. - status: - type: string - description: Thing Status - format: string - example: enabled - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the channel was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the channel was created. - xml: - name: thing - - ThingWithEmptySecret: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Thing unique identifier. - name: - type: string - example: thingName - description: Thing name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: Thing tags. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: ID of the domain to which thing belongs. - credentials: - type: object - properties: - identity: - type: string - example: thingidentity - description: Thing Identity for example email address. - secret: - type: string - example: "" - description: Thing secret password. - metadata: - type: object - example: { "model": "example" } - description: Arbitrary, object-encoded thing's data. - status: - type: string - description: Thing Status - format: string - example: enabled - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the channel was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the channel was created. - xml: - name: thing - - Channel: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Unique channel identifier generated by the service. - name: - type: string - example: channelName - description: Free-form channel name. Channel name is unique on the given hierarchy level. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: ID of the domain to which the group belongs. - parent_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Channel parent identifier. - description: - type: string - example: long channel description - description: Channel description, free form text. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded channels's data. - path: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879.bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Hierarchy path, concatenated ids of channel ancestors. - level: - type: integer - description: Level in hierarchy, distance from the root channel. - format: int32 - example: 2 - maximum: 5 - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Datetime when the channel was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Datetime when the channel was created. - status: - type: string - description: Channel Status - format: string - example: enabled - xml: - name: channel - - Policy: - type: object - properties: - owner_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Policy owner identifier. - subject: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Policy subject identifier. - object: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Policy object identifier. - actions: - type: array - minItems: 0 - items: - type: string - example: ["m_write", "g_add"] - description: Policy actions. - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the policy was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the policy was updated. - xml: - name: policy - - ThingsPage: - type: object - properties: - things: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/ThingWithEmptySecret" - 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: - - things - - total - - offset - - ChannelsPage: - type: object - properties: - channels: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Channel" - 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: - - channels - - total - - offset - - PoliciesPage: - type: object - properties: - policies: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Policy" - 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: - - policies - - total - - offset - - ThingUpdate: - type: object - properties: - name: - type: string - example: thingName - description: Thing name. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded thing's data. - required: - - name - - metadata - - ThingTags: - type: object - properties: - tags: - type: array - example: ["tag1", "tag2"] - description: Thing tags. - minItems: 0 - uniqueItems: true - items: - type: string - - ThingSecret: - type: object - properties: - secret: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: New thing secret. - required: - - secret - - ChannelUpdate: - type: object - properties: - name: - type: string - example: channelName - description: Free-form channel name. Channel name is unique on the given hierarchy level. - description: - type: string - example: long description but not too long - description: Channel description, free form text. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded channels's data. - required: - - name - - metadata - - description - - ConnectionReqSchema: - type: object - properties: - objects: - type: array - description: Channel IDs. - items: - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - subjects: - type: array - description: Thing IDs - items: - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - permission: - type: array - description: policy actions - items: - example: publish - - DisConnectionReqSchema: - type: object - properties: - objects: - type: array - description: Channel IDs. - items: - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - subjects: - type: array - description: Thing IDs - items: - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - Error: - type: object - properties: - error: - type: string - description: Error message - example: { "error": "malformed entity specification" } - - HealthRes: - type: object - properties: - status: - type: string - description: Service status. - enum: - - pass - version: - type: string - description: Service version. - example: 0.14.0 - commit: - type: string - description: Service commit hash. - example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62 - description: - type: string - description: Service description. - example: things service - build_time: - type: string - description: Service build time. - example: 1970-01-01_00:00:00 - - parameters: - ThingID: - name: thingID - description: Unique thing identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - MemberID: - name: memberID - description: Unique member identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - ThingName: - name: name - description: Thing's name. - in: query - schema: - type: string - required: false - example: "thingName" - - Status: - name: status - description: Thing account status. - in: query - schema: - type: string - default: enabled - required: false - example: enabled - - Tags: - name: tags - description: Thing tags. - in: query - schema: - type: array - minItems: 0 - uniqueItems: true - items: - type: string - required: false - example: ["yello", "orange"] - - ChannelName: - name: name - description: Channel's name. - in: query - schema: - type: string - required: false - example: "channelName" - - ChannelDescription: - name: name - description: Channel's description. - in: query - schema: - type: string - required: false - example: "channel description" - - chanID: - name: chanID - description: Unique channel identifier. - in: path - schema: - type: string - format: uuid - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - ParentId: - name: parentId - description: Unique parent identifier for a channel. - in: query - schema: - type: string - format: uuid - required: false - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - Level: - name: level - description: Level of hierarchy up to which to retrieve channels from given channel id. - in: query - schema: - type: integer - minimum: 1 - maximum: 5 - required: false - - Tree: - name: tree - description: Specify type of response, JSON array or tree. - in: query - required: false - schema: - type: boolean - default: false - - Metadata: - name: metadata - description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json. - in: query - schema: - type: string - minimum: 0 - required: false - - Limit: - name: limit - description: Size of the subset to retrieve. - in: query - schema: - type: integer - default: 10 - maximum: 100 - minimum: 1 - required: false - example: "100" - - Offset: - name: offset - description: Number of items to skip during retrieval. - in: query - schema: - type: integer - default: 0 - minimum: 0 - required: false - example: "0" - - Connected: - name: connected - description: Connection state of the subset to retrieve. - in: query - schema: - type: boolean - default: true - required: false - - requestBodies: - ThingCreateReq: - description: JSON-formatted document describing the new thing to be registered - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ThingReqObj" - - ThingUpdateReq: - description: JSON-formated document describing the metadata and name of thing to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ThingUpdate" - - ThingUpdateTagsReq: - description: JSON-formated document describing the tags of thing to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ThingTags" - - ThingUpdateSecretReq: - description: Secret change data. Thing can change its secret. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ThingSecret" - - ShareThingReq: - description: JSON-formated document describing the policy related to sharing things - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PolicyReqObj" - - AssignReq: - description: JSON-formated document describing the policy related to assigning members to a channel - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignReqObj" - - AssignUserReq: - description: JSON-formated document describing the policy related to assigning members to a channel - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignUserReqObj" - - AssignUsersReq: - description: JSON-formated document describing the policy related to assigning members to a channel - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignUsersReqObj" - - ChannelCreateReq: - description: JSON-formatted document describing the new channel to be registered - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ChannelReqObj" - - ChannelUpdateReq: - description: JSON-formated document describing the metadata and name of channel to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ChannelUpdate" - - ThingsCreateReq: - description: JSON-formatted document describing the new things. - required: true - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/ThingReqObj" - - ConnCreateReq: - description: JSON-formatted document describing the new connection. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ConnectionReqSchema" - - DisconnReq: - description: JSON-formatted document describing the entities for disconnection. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/DisConnectionReqSchema" - - responses: - ThingCreateRes: - description: Registered new thing. - headers: - Location: - schema: - type: string - format: url - description: Registered thing relative URL in the format `/things/` - content: - application/json: - schema: - $ref: "#/components/schemas/Thing" - links: - get: - operationId: getThing - parameters: - thingID: $response.body#/id - get_channels: - operationId: listChannelsConnectedToThing - parameters: - thingID: $response.body#/id - update: - operationId: updateThing - parameters: - thingID: $response.body#/id - update_tags: - operationId: updateThingTags - parameters: - thingID: $response.body#/id - update_secret: - operationId: updateThingSecret - parameters: - thingID: $response.body#/id - share: - operationId: shareThing - parameters: - thingID: $response.body#/id - unsahre: - operationId: unshareThing - parameters: - thingID: $response.body#/id - disable: - operationId: disableThing - parameters: - thingID: $response.body#/id - enable: - operationId: enableThing - parameters: - thingID: $response.body#/id - - ThingRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Thing" - links: - get_channels: - operationId: listChannelsConnectedToThing - parameters: - thingID: $response.body#/id - share: - operationId: shareThing - parameters: - thingID: $response.body#/id - unsahre: - operationId: unshareThing - parameters: - thingID: $response.body#/id - - ThingPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/ThingsPage" - - ThingsPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/ThingsPage" - - ChannelCreateRes: - description: Registered new channel. - headers: - Location: - schema: - type: string - format: url - description: Registered channel relative URL in the format `/channels/` - content: - application/json: - schema: - $ref: "#/components/schemas/Channel" - links: - get: - operationId: getChannel - parameters: - chanID: $response.body#/id - get_things: - operationId: listThingsInaChannel - parameters: - chanID: $response.body#/id - get_users: - operationId: listChannelsConnectedToUser - parameters: - memberID: $response.body#/id - get_groups: - operationId: listChannelsConnectedToGroup - parameters: - memberID: $response.body#/id - update: - operationId: updateChannel - parameters: - chanID: $response.body#/id - disable: - operationId: disableChannel - parameters: - chanID: $response.body#/id - enable: - operationId: enableChannel - parameters: - chanID: $response.body#/id - assign_users: - operationId: assignUsersToChannel - parameters: - chanID: $response.body#/id - unassign_users: - operationId: unassignUsersFromChannel - parameters: - chanID: $response.body#/id - assign_groups: - operationId: assignGroupsToChannel - parameters: - chanID: $response.body#/id - unassign_groups: - operationId: unassignGroupsFromChannel - parameters: - chanID: $response.body#/id - - ChannelRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Channel" - links: - get_things: - operationId: listThingsInaChannel - parameters: - chanID: $response.body#/id - get_users: - operationId: listChannelsConnectedToUser - parameters: - memberID: $response.body#/id - get_groups: - operationId: listChannelsConnectedToGroup - parameters: - memberID: $response.body#/id - assign_users: - operationId: assignUsersToChannel - parameters: - chanID: $response.body#/id - unassign_users: - operationId: unassignUsersFromChannel - parameters: - chanID: $response.body#/id - assign_groups: - operationId: assignGroupsToChannel - parameters: - chanID: $response.body#/id - unassign_groups: - operationId: unassignGroupsFromChannel - parameters: - chanID: $response.body#/id - - ChannelPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/ChannelsPage" - - ConnCreateRes: - description: Thing registered. - content: - application/json: - schema: - $ref: "#/components/schemas/PoliciesPage" - - DisconnRes: - description: Things disconnected. - - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "#/components/schemas/HealthRes" - - ServiceError: - description: Unexpected server-side error occurred. - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * Thing access: "Authorization: Bearer " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/twins.yml b/apis/api/openapi/twins.yml deleted file mode 100644 index 36261f5ff..000000000 --- a/apis/api/openapi/twins.yml +++ /dev/null @@ -1,431 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.1 -info: - title: Magistrala twins service - description: | - HTTP API for managing digital twins and their states. - Some useful links: - - [The Magistrala repository](https://github.com/absmach/magistrala) - contact: - email: info@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9018 - - url: https://localhost:9018 - -tags: - - name: twins - description: Everything about your Twins - externalDocs: - description: Find out more about twins - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /twins: - post: - operationId: createTwin - summary: Adds new twin - description: | - Adds new twin to the list of twins owned by user identified using - the provided access token. - tags: - - twins - requestBody: - $ref: "#/components/requestBodies/TwinReq" - responses: - "201": - $ref: "#/components/responses/TwinCreateRes" - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - get: - operationId: getTwins - summary: Retrieves twins - description: | - Retrieves a list of twins. Due to performance concerns, data - is retrieved in subsets. - tags: - - twins - parameters: - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Name" - - $ref: "#/components/parameters/Metadata" - responses: - "200": - $ref: "#/components/responses/TwinsPageRes" - "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" - - /twins/{twinID}: - get: - operationId: getTwin - summary: Retrieves twin info - tags: - - twins - parameters: - - $ref: "#/components/parameters/TwinID" - responses: - "200": - $ref: "#/components/responses/TwinRes" - "400": - description: Failed due to malformed twin's ID. - "401": - description: Missing or invalid access token provided. - "404": - description: Twin does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - put: - operationId: updateTwin - summary: Updates twin info - description: | - Update is performed by replacing the current resource data with values - provided in a request payload. Note that the twin's ID cannot be changed. - tags: - - twins - parameters: - - $ref: "#/components/parameters/TwinID" - requestBody: - $ref: "#/components/requestBodies/TwinReq" - responses: - "200": - description: Twin updated. - "400": - description: Failed due to malformed twin's ID or malformed JSON. - "401": - description: Missing or invalid access token provided. - "404": - description: Twin does not exist. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - delete: - operationId: removeTwin - summary: Removes a twin - description: Removes a twin. - tags: - - twins - parameters: - - $ref: "#/components/parameters/TwinID" - responses: - "204": - description: Twin removed. - "400": - description: Failed due to malformed twin's ID. - "401": - description: Missing or invalid access token provided - "404": - description: Twin does not exist. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /states/{twinID}: - get: - operationId: getStates - summary: Retrieves states of twin with id twinID - description: | - Retrieves a list of states. Due to performance concerns, data - is retrieved in subsets. - tags: - - states - parameters: - - $ref: "#/components/parameters/TwinID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - responses: - "200": - $ref: "#/components/responses/StatesPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: Twin 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: - parameters: - 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 - Name: - name: name - description: Twin name - in: query - schema: - type: string - required: false - Metadata: - name: metadata - description: | - Metadata filter. Filtering is performed matching the parameter with - metadata on top level. Parameter is json. - in: query - schema: - type: string - minimum: 0 - required: false - TwinID: - name: twinID - description: Unique twin identifier. - in: path - schema: - type: string - format: uuid - minimum: 1 - required: true - - schemas: - Attribute: - type: object - properties: - name: - type: string - description: Name of the attribute. - channel: - type: string - description: Magistrala channel used by attribute. - subtopic: - type: string - description: Subtopic used by attribute. - persist_state: - type: boolean - description: Trigger state creation based on the attribute. - Definition: - type: object - properties: - delta: - type: number - description: Minimal time delay before new state creation. - attributes: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Attribute" - TwinReqObj: - type: object - properties: - name: - type: string - description: Free-form twin name. - metadata: - type: object - description: Arbitrary, object-encoded twin's data. - definition: - $ref: "#/components/schemas/Definition" - TwinResObj: - type: object - properties: - owner: - type: string - description: Email address of Magistrala user that owns twin. - id: - type: string - format: uuid - description: Unique twin identifier generated by the service. - name: - type: string - description: Free-form twin name. - revision: - type: number - description: Oridnal revision number of twin. - created: - type: string - format: date - description: Twin creation date and time. - updated: - type: string - format: date - description: Twin update date and time. - definitions: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Definition" - metadata: - type: object - description: Arbitrary, object-encoded twin's data. - TwinsPage: - type: object - properties: - twins: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/TwinResObj" - 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. - required: - - twins - State: - type: object - properties: - twin_id: - type: string - format: uuid - description: ID of twin state belongs to. - id: - type: number - description: State position in a time row of states. - created: - type: string - format: date - description: State creation date. - payload: - type: object - description: Object-encoded states's payload. - StatesPage: - type: object - properties: - states: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/State" - 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. - required: - - states - - requestBodies: - TwinReq: - description: JSON-formatted document describing the twin to create or update. - content: - application/json: - schema: - $ref: "#/components/schemas/TwinReqObj" - required: true - - responses: - TwinCreateRes: - description: Created twin's relative URL (i.e. /twins/{twinID}). - headers: - Location: - content: - text/plain: - schema: - type: string - TwinRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/TwinResObj" - links: - update: - operationId: updateTwin - parameters: - twinID: $response.body#/id - delete: - operationId: removeTwin - parameters: - twinID: $response.body#/id - states: - operationId: getStates - parameters: - twinID: $response.body#/id - TwinsPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/TwinsPage" - StatesPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/StatesPage" - ServiceError: - description: Unexpected server-side error occurred. - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "./schemas/HealthInfo.yml" - - securitySchemes: - bearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * Users access: "Authorization: Bearer " - -security: - - bearerAuth: [] diff --git a/apis/api/openapi/users.yml b/apis/api/openapi/users.yml deleted file mode 100644 index 415a81a0f..000000000 --- a/apis/api/openapi/users.yml +++ /dev/null @@ -1,2312 +0,0 @@ -# Copyright (c) Abstract Machines -# SPDX-License-Identifier: Apache-2.0 - -openapi: 3.0.3 -info: - title: Magistrala Users Service - description: | - This is the Users Server based on the OpenAPI 3.0 specification. It is the HTTP API for managing platform users. 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@abstractmachines.fr - license: - name: Apache 2.0 - url: https://github.com/absmach/magistrala/blob/main/LICENSE - version: 0.14.0 - -servers: - - url: http://localhost:9002 - - url: https://localhost:9002 - -tags: - - name: Users - description: Everything about your Users - externalDocs: - description: Find out more about users - url: https://docs.magistrala.abstractmachines.fr/ - - name: Groups - description: Everything about your Groups - externalDocs: - description: Find out more about users groups - url: https://docs.magistrala.abstractmachines.fr/ - -paths: - /users: - post: - operationId: createUser - tags: - - Users - summary: Registers user account - description: | - Registers new user account given email and password. New account will - be uniquely identified by its email address. - requestBody: - $ref: "#/components/requestBodies/UserCreateReq" - responses: - "201": - $ref: "#/components/responses/UserCreateRes" - "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 identity. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - get: - operationId: listUsers - tags: - - Users - summary: List users - description: | - Retrieves a list of users. 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/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - - $ref: "#/components/parameters/FirstName" - - $ref: "#/components/parameters/LastName" - - $ref: "#/components/parameters/Username" - - $ref: "#/components/parameters/Email" - - $ref: "#/components/parameters/Tags" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: | - Missing or invalid access token provided. - This endpoint is available only for administrators. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/profile: - get: - operationId: getProfile - summary: Gets info on currently logged in user. - description: | - Gets info on currently logged in user. Info is obtained using - authorization token - tags: - - Users - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}: - get: - operationId: getUser - summary: Retrieves a user - description: | - Retrieves a specific user that is identifier by the user ID. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - patch: - operationId: updateUser - summary: Updates first, last name and metadata of the user. - description: | - Updates name and metadata of the user with provided ID. Name and metadata - is updated using authorization token and the new received info. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UserUpdateReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "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" - - delete: - summary: Delete a user - description: | - Delete a specific user that is identifier by the user ID. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - security: - - bearerAuth: [] - responses: - "204": - description: User deleted. - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "404": - description: A non-existent entity request. - "405": - description: Method not allowed. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/username: - patch: - operationId: updateUsername - summary: Updates user's username. - description: | - Updates username of the user with provided ID. Username is - updated using authorization token and the new received username. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UpdateUsernameReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "409": - description: Failed due to using an existing username. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/tags: - patch: - operationId: updateTags - summary: Updates tags of the user. - description: | - Updates tags of the user with provided ID. Tags is updated using - authorization token and the new tags received in request. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UserUpdateTagsReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/picture: - patch: - operationId: updateProfilePicture - summary: Updates the user's profile picture. - description: | - Updates the user's profile picture with provided ID. Profile picture is - updated using authorization token and the new received picture. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UserUpdateProfilePictureReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/email: - patch: - operationId: updateEmail - summary: Updates email of the user. - description: | - Updates email of the user with provided ID. Email is - updated using authorization token and the new received email. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UserUpdateEmailReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "409": - description: Failed due to using an existing email. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/role: - patch: - operationId: updateRole - summary: Updates the user's role. - description: | - Updates role for the user with provided ID. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - requestBody: - $ref: "#/components/requestBodies/UserUpdateRoleReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "403": - description: Failed to perform authorization over the entity. - "404": - description: Failed due to non existing user. - "401": - description: Missing or invalid access token provided. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/disable: - post: - operationId: disableUser - summary: Disables a user - description: | - Disables a specific user that is identifier by the user ID. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "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. - "409": - description: Failed due to already disabled user. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/{userID}/enable: - post: - operationId: enableUser - summary: Enables a user - description: | - Enables a specific user that is identifier by the user ID. - tags: - - Users - parameters: - - $ref: "#/components/parameters/UserID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "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. - "409": - description: Failed due to already enabled user. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/secret: - patch: - operationId: updateSecret - summary: Updates secret of currently logged in user. - description: | - Updates secret of currently logged in user. Secret is updated using - authorization token and the new received info. - tags: - - Users - requestBody: - $ref: "#/components/requestBodies/UserUpdateSecretReq" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserRes" - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "404": - description: Failed due to non existing user. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /users/search: - get: - operationId: searchUsers - summary: Search users - description: | - Search users by name and identity. - tags: - - Users - parameters: - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Username" - - $ref: "#/components/parameters/FirstName" - - $ref: "#/components/parameters/LastName" - - $ref: "#/components/parameters/Email" - - $ref: "#/components/parameters/UserID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "500": - $ref: "#/components/responses/ServiceError" - - /password/reset-request: - post: - operationId: requestPasswordReset - summary: User password reset request - description: | - Generates a reset token and sends and - email with link for resetting password. - tags: - - Users - parameters: - - $ref: "#/components/parameters/Referer" - requestBody: - $ref: "#/components/requestBodies/RequestPasswordReset" - responses: - "201": - description: Users link for resetting password. - "400": - description: Failed due to malformed JSON. - "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" - - /password/reset: - put: - operationId: resetPassword - summary: User password reset endpoint - description: | - When user gets reset token, after he submitted - email to `/password/reset-request`, posting a - new password along to this endpoint will change password. - tags: - - Users - requestBody: - $ref: "#/components/requestBodies/PasswordReset" - responses: - "201": - description: User link . - "400": - description: Failed due to malformed JSON. - "401": - description: Missing or invalid access token provided. - "404": - description: Entity not found. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/users: - get: - operationId: listUsersInGroup - tags: - - Users - summary: List users in a group - description: | - Retrieves a list of users in a group. 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: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Level" - - $ref: "#/components/parameters/Tree" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/GroupName" - - $ref: "#/components/parameters/ParentID" - responses: - "200": - $ref: "#/components/responses/MembersPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: | - Missing or invalid access token provided. - This endpoint is available only for administrators. - "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}/channels/{channelID}/users: - get: - operationId: listUsersInChannel - tags: - - Users - summary: List users in a channel - description: | - Retrieves a list of users in a channel. 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: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/ChannelID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Level" - - $ref: "#/components/parameters/Tree" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/ChannelName" - - $ref: "#/components/parameters/ParentID" - responses: - "200": - $ref: "#/components/responses/MembersPageRes" - "400": - description: Failed due to malformed query parameters. - "401": - description: | - Missing or invalid access token provided. - This endpoint is available only for administrators. - "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" - - /users/tokens/issue: - post: - operationId: issueToken - summary: Issue Token - description: | - Issue Access and Refresh Token used for authenticating into the system. - tags: - - Users - requestBody: - $ref: "#/components/requestBodies/IssueTokenReq" - responses: - "200": - $ref: "#/components/responses/TokenRes" - "400": - description: Failed due to malformed JSON. - "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" - - /users/tokens/refresh: - post: - operationId: refreshToken - summary: Refresh Token - description: | - Refreshes Access and Refresh Token used for authenticating into the system. - tags: - - Users - security: - - refreshAuth: [] - responses: - "200": - $ref: "#/components/responses/TokenRes" - "400": - description: Failed due to malformed JSON. - "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" - - /{domainID}/groups: - post: - operationId: createGroup - tags: - - Groups - summary: Creates new group - description: | - Creates new group that can be used for grouping entities. New account will - be uniquely identified by its identity. - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - requestBody: - $ref: "#/components/requestBodies/GroupCreateReq" - security: - - bearerAuth: [] - responses: - "201": - $ref: "#/components/responses/GroupCreateRes" - "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" - - get: - operationId: listGroups - summary: Lists groups. - description: | - Lists groups up to a max level of hierarchy that can be fetched in one - request ( max level = 5). Result can be filtered by metadata. Groups will - be returned as JSON array or JSON tree. Due to performance concerns, result - is returned in subsets. - tags: - - Groups - security: - - bearerAuth: [] - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Level" - - $ref: "#/components/parameters/Tree" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/GroupName" - - $ref: "#/components/parameters/ParentID" - responses: - "200": - $ref: "#/components/responses/GroupPageRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}: - get: - operationId: getGroup - summary: Gets group info. - description: | - Gets info on a group specified by id. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/GroupRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - put: - operationId: updateGroup - summary: Updates group data. - description: | - Updates Name, Description or Metadata of a group. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - security: - - bearerAuth: [] - requestBody: - $ref: "#/components/requestBodies/GroupUpdateReq" - responses: - "200": - $ref: "#/components/responses/GroupRes" - "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: Group does not exist. - "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" - delete: - summary: Delete group for a group with the given id. - description: | - Delete group removes a group with the given id from repo - and removes all the policies related to this group. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - security: - - bearerAuth: [] - responses: - "204": - description: Group deleted. - "400": - description: Failed due to malformed query parameters. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access to group id. - "404": - description: A non-existent entity request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/children: - get: - operationId: listChildren - summary: List children of a certain group - description: | - Lists groups up to a max level of hierarchy that can be fetched in one - request ( max level = 5). Result can be filtered by metadata. Groups will - be returned as JSON array or JSON tree. Due to performance concerns, result - is returned in subsets. - tags: - - Groups - security: - - bearerAuth: [] - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Level" - - $ref: "#/components/parameters/Tree" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/GroupName" - - $ref: "#/components/parameters/ParentID" - responses: - "200": - $ref: "#/components/responses/GroupPageRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/parents: - get: - operationId: listParents - summary: List parents of a certain group - description: | - Lists groups up to a max level of hierarchy that can be fetched in one - request ( max level = 5). Result can be filtered by metadata. Groups will - be returned as JSON array or JSON tree. Due to performance concerns, result - is returned in subsets. - tags: - - Groups - security: - - bearerAuth: [] - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Level" - - $ref: "#/components/parameters/Tree" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/GroupName" - - $ref: "#/components/parameters/ParentID" - responses: - "200": - $ref: "#/components/responses/GroupPageRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/enable: - post: - operationId: enableGroup - summary: Enables a group - description: | - Enables a specific group that is identifier by the group ID. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/GroupRes" - "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. - "409": - description: Failed due to already enabled group. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/disable: - post: - operationId: disableGroup - summary: Disables a group - description: | - Disables a specific group that is identifier by the group ID. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/GroupRes" - "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. - "409": - description: Failed due to already disabled group. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/users/assign: - post: - operationId: assignUser - summary: Assigns a user to a group - description: | - Assigns a specific user to a group that is identifier by the group ID. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - requestBody: - $ref: "#/components/requestBodies/AssignUserReq" - security: - - bearerAuth: [] - responses: - "200": - description: Member assigned. - "400": - description: Failed due to malformed group's 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. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/groups/{groupID}/users/unassign: - post: - operationId: unassignUser - summary: Unassigns a user to a group - description: | - Unassigns a specific user to a group that is identifier by the group ID. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/GroupID" - requestBody: - $ref: "#/components/requestBodies/AssignUserReq" - security: - - bearerAuth: [] - responses: - "204": - description: Member unassigned. - "400": - description: Failed due to malformed group's 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. - "415": - description: Missing or invalid content type. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/channels/{memberID}/groups: - get: - operationId: listGroupsInChannel - summary: Get group associated with the member - description: | - Gets groups associated with the channel member specified by id. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/MemberID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - - $ref: "#/components/parameters/Tags" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/GroupPageRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - - /{domainID}/users/{memberID}/groups: - get: - operationId: listGroupsByUser - summary: Get group associated with the member - description: | - Gets groups associated with the user member specified by id. - tags: - - Groups - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/MemberID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - - $ref: "#/components/parameters/Tags" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/GroupPageRes" - "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: Group does not exist. - "422": - description: Database can't process request. - "500": - $ref: "#/components/responses/ServiceError" - /{domainID}/users: - get: - summary: List users assigned to domain - description: | - List users assigned to domain that is identified by the domain ID. - tags: - - Domains - parameters: - - $ref: "auth.yml#/components/parameters/DomainID" - - $ref: "#/components/parameters/Limit" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Metadata" - - $ref: "#/components/parameters/Status" - security: - - bearerAuth: [] - responses: - "200": - $ref: "#/components/responses/UserPageRes" - description: List of users assigned to domain. - "400": - description: Failed due to malformed domain's ID. - "401": - description: Missing or invalid access token provided. - "403": - description: Unauthorized access the domain ID. - "404": - description: A non-existent entity request. - "422": - description: Database can't process request. - "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: - UserReqObj: - type: object - properties: - first_name: - type: string - example: firstName - description: User's first name. - last_name: - type: string - example: lastName - description: User's last name. - email: - type: string - example: "admin@example.com" - description: User's email address will be used as its unique identifier. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: User tags. - credentials: - type: object - properties: - username: - type: string - example: "admin" - description: User's username for example 'admin' will be used as its unique identifier. - secret: - type: string - format: password - example: password - minimum: 8 - description: Free-form account secret used for acquiring auth token(s). - metadata: - type: object - example: { "domain": "example.com" } - description: Arbitrary, object-encoded user's data. - profile_picture: - type: string - example: "https://example.com/profile.jpg" - description: User's profile picture URL that is represented as a string. - status: - type: string - description: User Status - format: string - example: enabled - required: - - credentials - - GroupReqObj: - type: object - properties: - name: - type: string - example: groupName - description: Free-form group name. Group name is unique on the given hierarchy level. - description: - type: string - example: long group description - description: Group description, free form text. - parent_id: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Id of parent group, it must be existing group. - metadata: - type: object - example: { "domain": "example.com" } - description: Arbitrary, object-encoded groups's data. - status: - type: string - description: Group Status - format: string - example: enabled - required: - - name - - User: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - first_name: - type: string - example: John - description: User's first name. - last_name: - type: string - example: Doe - description: User's last name. - tags: - type: array - minItems: 0 - items: - type: string - example: ["tag1", "tag2"] - description: User tags. - email: - type: string - example: "john.doe@magistrala.com" - description: User email for example email address. - credentials: - type: object - properties: - username: - type: string - example: john_doe - description: User's username for example john_doe for Mr John Doe. - metadata: - type: object - example: { "address": "example" } - description: Arbitrary, object-encoded user's data. - profile_picture: - type: string - example: "https://example.com/profile.jpg" - description: User's profile picture URL that is represented as a string. - status: - type: string - description: User Status - format: string - example: enabled - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - xml: - name: user - - Group: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Unique group identifier generated by the service. - name: - type: string - example: groupName - description: Free-form group name. Group name is unique on the given hierarchy level. - domain_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: ID of the domain to which the group belongs.. - parent_id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Group parent identifier. - description: - type: string - example: long group description - description: Group description, free form text. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded groups's data. - path: - type: string - example: bb7edb32-2eac-4aad-aebe-ed96fe073879.bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: Hierarchy path, concatenated ids of group ancestors. - level: - type: integer - description: Level in hierarchy, distance from the root group. - format: int32 - example: 2 - maximum: 5 - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Datetime when the group was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Datetime when the group was created. - status: - type: string - description: Group Status - format: string - example: enabled - xml: - name: group - - Members: - type: object - properties: - id: - type: string - format: uuid - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - description: User unique identifier. - first_name: - type: string - example: John - description: User's first name. - last_name: - type: string - example: Doe - description: User's last name. - email: - type: string - example: user@magistrala.com - description: User's email address. - tags: - type: array - minItems: 0 - items: - type: string - example: ["computations", "datasets"] - description: User tags. - credentials: - type: object - properties: - username: - type: string - example: john_doe - description: User's username. - secret: - type: string - example: password - minimum: 8 - description: User secret password. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded user's data. - status: - type: string - description: User Status - format: string - example: enabled - created_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - updated_at: - type: string - format: date-time - example: "2019-11-26 13:31:52" - description: Time when the group was created. - xml: - name: members - - UsersPage: - type: object - properties: - users: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/User" - 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: - - users - - total - - offset - - GroupsPage: - type: object - properties: - groups: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Group" - 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: - - groups - - total - - offset - - MembersPage: - type: object - properties: - members: - type: array - minItems: 0 - uniqueItems: true - items: - $ref: "#/components/schemas/Members" - 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: - - members - - total - - level - - UserUpdate: - type: object - properties: - first_name: - type: string - example: firstName - description: User's first name. - last_name: - type: string - example: lastName - description: User's last name. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded user's data. - required: - - first_name - - last_name - - metadata - - UserTags: - type: object - properties: - tags: - type: array - example: ["yello", "orange"] - description: User tags. - minItems: 0 - uniqueItems: true - items: - type: string - - UserProfilePicture: - type: object - properties: - profile_picture: - type: string - example: "https://example.com/profile.jpg" - description: User's profile picture URL that is represented as a string. - required: - - profile_picture - - Email: - type: object - properties: - email: - type: string - example: user@magistrala.com - description: User email address. - required: - - email - - UserSecret: - type: object - properties: - old_secret: - type: string - example: oldpassword - minimum: 8 - description: Old user secret password. - new_secret: - type: string - example: newpassword - minimum: 8 - description: New user secret password. - required: - - old_secret - - new_secret - - UserRole: - type: object - properties: - role: - type: string - enum: ["admin", "user"] - example: user - description: User role example. - required: - - role - - Username: - type: object - properties: - username: - type: string - example: "admin" - description: User's username for example 'admin' will be used as its unique identifier. - required: - - username - - GroupUpdate: - type: object - properties: - name: - type: string - example: groupName - description: Free-form group name. Group name is unique on the given hierarchy level. - description: - type: string - example: long description but not too long - description: Group description, free form text. - metadata: - type: object - example: { "role": "general" } - description: Arbitrary, object-encoded groups's data. - required: - - name - - metadata - - description - - AssignReqObj: - type: object - properties: - members: - type: array - minItems: 0 - items: - type: string - description: Members IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - relation: - type: string - example: "m_write" - description: Permission relations. - member_kind: - type: string - example: "user" - description: Member kind. - required: - - members - - relation - - member_kind - - AssignUserReqObj: - type: object - properties: - user_ids: - type: array - minItems: 0 - items: - type: string - description: User IDs - example: - [ - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - "bb7edb32-2eac-4aad-aebe-ed96fe073879", - ] - relation: - type: string - example: "m_write" - description: Permission relations. - required: - - user_ids - - relation - - IssueToken: - type: object - properties: - identity: - type: string - example: user@magistrala.com - description: User identity - email address. - secret: - type: string - example: password - minimum: 8 - description: User secret password. - required: - - identity - - secret - - Error: - type: object - properties: - error: - type: string - description: Error message - example: { "error": "malformed entity specification" } - - HealthRes: - type: object - properties: - status: - type: string - description: Service status. - enum: - - pass - version: - type: string - description: Service version. - example: 0.0.1 - commit: - type: string - description: Service commit hash. - example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62 - description: - type: string - description: Service description. - example: service - build_time: - type: string - description: Service build time. - example: 1970-01-01_00:00:00 - - parameters: - Referer: - name: Referer - description: Host being sent by browser. - in: header - schema: - type: string - required: true - - UserID: - name: userID - description: Unique user identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - Username: - name: username - description: User's username. - in: query - schema: - type: string - required: false - example: "username" - - FirstName: - name: first_name - description: User's first name. - in: query - schema: - type: string - required: false - example: "Jane" - - LastName: - name: last_name - description: User's last name. - in: query - schema: - type: string - required: false - example: "Doe" - - Email: - name: email - description: User's email address. - in: query - schema: - type: string - format: email - required: false - example: "admin@example.com" - - Status: - name: status - description: User account status. - in: query - schema: - type: string - default: enabled - required: false - example: enabled - - Tags: - name: tags - description: User tags. - in: query - schema: - type: array - minItems: 0 - uniqueItems: true - items: - type: string - required: false - example: ["yello", "orange"] - - GroupName: - name: name - description: Group's name. - in: query - schema: - type: string - required: false - example: "groupName" - - ChannelName: - name: name - description: Channel's name. - in: query - schema: - type: string - required: false - example: "channelName" - - GroupDescription: - name: name - description: Group's description. - in: query - schema: - type: string - required: false - example: "group description" - - GroupID: - name: groupID - description: Unique group identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - ChannelID: - name: channelID - description: Unique channel identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - MemberID: - name: memberID - description: Unique member identifier. - in: path - schema: - type: string - format: uuid - minLength: 36 - maxLength: 36 - pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" - required: true - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - ParentID: - name: parentID - description: Unique parent identifier for a group. - in: query - schema: - type: string - format: uuid - required: false - example: bb7edb32-2eac-4aad-aebe-ed96fe073879 - - Level: - name: level - description: Level of hierarchy up to which to retrieve groups from given group id. - in: query - schema: - type: integer - minimum: 1 - maximum: 5 - required: false - - Tree: - name: tree - description: Specify type of response, JSON array or tree. - in: query - required: false - schema: - type: boolean - default: false - - Metadata: - name: metadata - description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json. - in: query - schema: - type: string - minimum: 0 - required: false - - Limit: - name: limit - description: Size of the subset to retrieve. - in: query - schema: - type: integer - default: 10 - maximum: 100 - minimum: 1 - required: false - example: "100" - - Offset: - name: offset - description: Number of items to skip during retrieval. - in: query - schema: - type: integer - default: 0 - minimum: 0 - required: false - example: "0" - - requestBodies: - UserCreateReq: - description: JSON-formatted document describing the new user to be registered - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserReqObj" - - UserUpdateReq: - description: JSON-formated document describing the metadata and name of user to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserUpdate" - - UserUpdateTagsReq: - description: JSON-formated document describing the tags of user to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserTags" - - UserUpdateProfilePictureReq: - description: JSON-formated document describing the profile picture of user to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserProfilePicture" - - UserUpdateEmailReq: - description: Email change data. User can change its email. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Email" - - UserUpdateSecretReq: - description: Secret change data. User can change its secret. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserSecret" - - UserUpdateRoleReq: - description: JSON-formated document describing the role of the user to be updated - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserRole" - - UpdateUsernameReq: - description: JSON-formated document describing the username of the user to be updated - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Username" - - GroupCreateReq: - description: JSON-formatted document describing the new group to be registered - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GroupReqObj" - - GroupUpdateReq: - description: JSON-formated document describing the metadata and name of group to be update - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GroupUpdate" - - AssignReq: - description: JSON-formated document describing the policy related to assigning members to a group - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignReqObj" - - AssignUserReq: - description: JSON-formated document describing the policy related to assigning users to a group - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignUserReqObj" - - IssueTokenReq: - description: Login credentials. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/IssueToken" - - RequestPasswordReset: - description: Initiate password request procedure. - required: true - content: - application/json: - schema: - type: object - properties: - email: - type: string - format: email - description: User email. - host: - type: string - example: examplehost - description: Email host. - - PasswordReset: - description: Password reset request data, new password and token that is appended on password reset link received in email. - content: - application/json: - schema: - type: object - properties: - password: - type: string - format: password - description: New password. - example: 12345678 - minimum: 8 - confirm_password: - type: string - format: password - description: New confirmation password. - example: 12345678 - minimum: 8 - token: - type: string - format: jwt - description: Reset token generated and sent in email. - - PasswordChange: - description: Password change data. User can change its password. - required: true - content: - application/json: - schema: - type: object - properties: - password: - type: string - format: password - minimum: 8 - description: New password. - old_password: - type: string - minimum: 8 - format: password - description: Old password. - - responses: - UserCreateRes: - description: Registered new user. - headers: - Location: - schema: - type: string - format: url - description: Registered user relative URL in the format `/users/` - content: - application/json: - schema: - $ref: "#/components/schemas/User" - links: - get: - operationId: getUser - parameters: - userID: $response.body#/id - get_groups: - operationId: listUsersInGroup - parameters: - groupID: $response.body#/id - get_channels: - operationId: listUsersInChannel - parameters: - channelID: $response.body#/id - update: - operationId: updateUser - parameters: - userID: $response.body#/id - update_username: - operationId: updateUsername - parameters: - userID: $response.body#/id - update_tags: - operationId: updateTags - parameters: - userID: $response.body#/id - update_profile_picture: - operationId: updateProfilePicture - parameters: - userID: $response.body#/id - update_email: - operationId: updateEmail - parameters: - userID: $response.body#/id - update_role: - operationId: updateRole - parameters: - userID: $response.body#/id - disable: - operationId: disableUser - parameters: - userID: $response.body#/id - enable: - operationId: enableUser - parameters: - userID: $response.body#/id - - UserRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/User" - links: - get_groups: - operationId: listUsersInGroup - parameters: - groupID: $response.body#/id - get_channels: - operationId: listUsersInChannel - parameters: - channelID: $response.body#/id - - UserPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/UsersPage" - - GroupCreateRes: - description: Registered new group. - headers: - Location: - schema: - type: string - format: url - description: Registered group relative URL in the format `/groups/` - content: - application/json: - schema: - $ref: "#/components/schemas/Group" - links: - get: - operationId: getGroup - parameters: - groupID: $response.body#/id - get_children: - operationId: listChildren - parameters: - groupID: $response.body#/id - get_parent: - operationId: listParents - parameters: - groupID: $response.body#/id - get_channels: - operationId: listGroupsInChannel - parameters: - memberID: $response.body#/id - get_users: - operationId: listGroupsByUser - parameters: - memberID: $response.body#/id - update: - operationId: updateGroup - parameters: - groupID: $response.body#/id - disable: - operationId: disableGroup - parameters: - groupID: $response.body#/id - enable: - operationId: enableGroup - parameters: - groupID: $response.body#/id - assign: - operationId: assignUser - parameters: - groupID: $response.body#/id - unassign: - operationId: unassignUser - parameters: - groupID: $response.body#/id - - GroupRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/Group" - links: - get_children: - operationId: listChildren - parameters: - groupID: $response.body#/id - get_parent: - operationId: listParents - parameters: - groupID: $response.body#/id - get_channels: - operationId: listGroupsInChannel - parameters: - memberID: $response.body#/id - get_users: - operationId: listGroupsByUser - parameters: - memberID: $response.body#/id - assign: - operationId: assignUser - parameters: - groupID: $response.body#/id - unassign: - operationId: unassignUser - parameters: - groupID: $response.body#/id - - GroupPageRes: - description: Data retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/GroupsPage" - - MembersPageRes: - description: Group members retrieved. - content: - application/json: - schema: - $ref: "#/components/schemas/MembersPage" - - TokenRes: - description: JSON-formated document describing the user access token used for authenticating into the syetem and refresh token used for generating another access token - content: - application/json: - schema: - type: object - properties: - access_token: - type: string - example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjU3OTMwNjksImlhdCI6MTY2NTc1NzA2OSwiaXNzIjoibWFpbmZsdXguYXV0aCIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzdWVyX2lkIjoiZmRjZWVhNWYtNjYxNy00MjY1LWJhZDUtMzYxOTNhOTQ0NjMwIiwidHlwZSI6MH0.3gNd_x01QEiZfQxuQoEyqCqTrcxRkXHO7A4iG_gzu3c - description: User access token. - refresh_token: - type: string - example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjU3OTMwNjksImlhdCI6MTY2NTc1NzA2OSwiaXNzIjoibWFpbmZsdXguYXV0aCIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzdWVyX2lkIjoiZmRjZWVhNWYtNjYxNy00MjY1LWJhZDUtMzYxOTNhOTQ0NjMwIiwidHlwZSI6MH0.3gNd_x01QEiZfQxuQoEyqCqTrcxRkXHO7A4iG_gzu3c - description: User refresh token. - access_type: - type: string - example: access - description: User access token type. - - HealthRes: - description: Service Health Check. - content: - application/health+json: - schema: - $ref: "#/components/schemas/HealthRes" - - 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 " - - refreshAuth: - type: http - scheme: bearer - bearerFormat: JWT - description: | - * User refresh token used to get another access token: "Authorization: Bearer " -security: - - bearerAuth: [] - - refreshAuth: [] diff --git a/swagger-config.json b/swagger-config.json index a706072bf..e1a81d1c4 100644 --- a/swagger-config.json +++ b/swagger-config.json @@ -1 +1 @@ -{"urls":[{"name":"auth.yml","url":"apis/api/openapi/auth.yml"},{"name":"bootstrap.yml","url":"apis/api/openapi/bootstrap.yml"},{"name":"certs.yml","url":"apis/api/openapi/certs.yml"},{"name":"http.yml","url":"apis/api/openapi/http.yml"},{"name":"invitations.yml","url":"apis/api/openapi/invitations.yml"},{"name":"journal.yml","url":"apis/api/openapi/journal.yml"},{"name":"notifiers.yml","url":"apis/api/openapi/notifiers.yml"},{"name":"provision.yml","url":"apis/api/openapi/provision.yml"},{"name":"readers.yml","url":"apis/api/openapi/readers.yml"},{"name":"things.yml","url":"apis/api/openapi/things.yml"},{"name":"twins.yml","url":"apis/api/openapi/twins.yml"},{"name":"users.yml","url":"apis/api/openapi/users.yml"}]} +{"urls":[{"name":"bootstrap.yml","url":"apis/api/openapi/bootstrap.yml"},{"name":"notifiers.yml","url":"apis/api/openapi/notifiers.yml"},{"name":"readers.yml","url":"apis/api/openapi/readers.yml"}]}