mirror of
https://github.com/absmach/supermq.git
synced 2026-06-23 06:40:19 +00:00
b1ackd0t
502 lines
13 KiB
YAML
502 lines
13 KiB
YAML
# 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/master/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.
|
|
"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.
|
|
"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:
|
|
"200":
|
|
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/{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.
|
|
"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.
|
|
"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
|
|
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
|
|
- viewer
|
|
- member
|
|
- 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
|
|
- viewer
|
|
- member
|
|
- 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_name> 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
|
|
- viewer
|
|
- member
|
|
- 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 <user_access_token>"
|
|
|
|
security:
|
|
- bearerAuth: []
|