opensource/magistrala
1
0
Fork 0
mirror of https://github.com/absmach/magistrala.git synced 2026-06-23 04:10:28 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

deploy: cddfdf4038

Browse Source
This commit is contained in:
drasko
2021-06-23 11:38:02 +00:00
commit 0e0a0b031c
39 changed files with 3935 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.nojekyll
View File
50x.html
+21
View File
@@ -0,0 +1,21 @@
<!DOCTYPE html>
<html>
<head>
<title>Error</title>
<style>
body {
width: 35em;
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
</style>
</head>
<body>
<h1>An error occurred.</h1>
<p>Sorry, the page you are looking for is currently unavailable.<br/>
Please try again later.</p>
<p>If you are the system administrator of this resource then you should check
the error log for details.</p>
<p><em>Faithfully yours, nginx.</em></p>
</body>
</html>
50x.html.gz
BIN
View File
Binary file not shown.
CNAME
+1
View File
@@ -0,0 +1 @@
api.mainflux.io
apis/auth.yml
+611
View File
@@ -0,0 +1,611 @@
openapi: 3.0.1
info:
title: Mainflux authentication service
description: HTTP API for managing platform API keys.
version: "1.0.0"
paths:
/keys:
post:
summary: Issue API key
description: |
Generates a new API key. Thew new API key will
be uniquely identified by its ID.
tags:
- auth
requestBody:
$ref: "#/components/requestBodies/KeyRequest"
responses:
'201':
description: Issued new key.
'400':
description: Failed due to malformed JSON.
'409':
description: Failed due to using already existing ID.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
/keys/{id}:
get:
summary: Gets API key details.
description: |
Gets API key details for the given key.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ApiKeyId"
responses:
'200':
$ref: "#/components/responses/KeyRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
delete:
summary: Revoke API key
description: |
Revoke API key identified by the given ID.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ApiKeyId"
responses:
'204':
description: Key revoked.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/groups:
post:
summary: Creates new group
description: |
Creates new group that can be used for grouping entities - things, users.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/requestBodies/GroupCreateReq"
responses:
'201':
$ref: "#/components/responses/GroupCreateRes"
'400':
description: Failed due to malformed JSON.
'409':
description: Failed due to using an existing email address.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
get:
summary: Gets all groups.
description: |
Gets all 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.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/Level"
- $ref: "#/components/parameters/Metadata"
- $ref: "#/components/parameters/Tree"
responses:
'200':
$ref: "#/components/responses/GroupsPageRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
/groups/{groupId}:
get:
summary: Gets group info.
description: |
Gets info on a group specified by id.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
responses:
'200':
$ref: "#/components/responses/GroupRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
put:
summary: Updates group data.
description: |
Updates Name, Description or Metadata of a group.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
requestBody:
$ref: "#/components/requestBodies/GroupUpdateReq"
responses:
'200':
description: Group updated.
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
delete:
summary: Deletes group.
description: |
Deletes group. If group is parent and descendant groups do not have any members
child groups will be deleted. Group cannot be deleted if has members or if
any descendant group has members.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
- $ref: "#/components/parameters/Level"
- $ref: "#/components/parameters/Metadata"
- $ref: "#/components/parameters/Tree"
responses:
'204':
description: Group removed.
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
/groups/{groupId}/children:
get:
summary: Gets group children.
description: |
Gets the whole tree of descendants of group for given id including itself.
For performance reason request is limited up to a given level of hierarchy
(max. 5).
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
- $ref: "#/components/parameters/Level"
- $ref: "#/components/parameters/Metadata"
- $ref: "#/components/parameters/Tree"
responses:
'200':
$ref: "#/components/responses/GroupsPageRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
/groups/{groupId}/parents:
get:
summary: Gets group info.
description: |
Gets a direct line of ancestors for a group specified by id.
Result is up to a specified hierarchy level or up to a root group.
Result can be a JSON array or a JSON tree.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
- $ref: "#/components/parameters/Level"
- $ref: "#/components/parameters/Metadata"
- $ref: "#/components/parameters/Tree"
responses:
'200':
$ref: "#/components/responses/GroupsPageRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Group does not exist.
'500':
$ref: "#/components/responses/ServiceError"
/groups/{groupId}/members:
post:
summary: Assigns members to a group.
description: |
Assigns thing or user id to a group.
tags:
- auth
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
requestBody:
$ref: "#/components/requestBodies/MembersReq"
responses:
'201':
$ref: "#/components/responses/GroupCreateRes"
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'409':
description: Failed due to using an existing email address.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
get:
summary: Gets members of a group.
description: |
Array of member ids that are in the group specified with groupID.
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Limit"
responses:
'200':
$ref: "#/components/responses/MembersRes"
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/members/{memberId}/groups:
get:
summary: Gets memberships for a member with member id.
description: |
Array of groups that member belongs to.
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/MemberId"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Metadata"
responses:
'200':
$ref: "#/components/responses/GroupRes"
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
components:
schemas:
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.
GroupReqSchema:
type: object
properties:
name:
type: string
description: |
Free-form group name. Group name is unique on the given hierarchy level.
description:
type: string
description: Group description, free form text.
parent_id:
type: string
format: ulid
description: Id of parent group, it must be existing group.
metadata:
type: object
description: Arbitrary, object-encoded group's data.
GroupUpdateSchema:
type: object
properties:
name:
type: string
description: |
Free-form group name. Group name is unique on the given hierarchy level.
description:
type: string
description: Group description, free form text.
metadata:
type: object
description: Arbitrary, object-encoded group's data.
GroupResSchema:
type: object
properties:
id:
type: string
format: ulid
description: Unique group identifier generated by the service.
name:
type: string
description: Free-form group name.
parent_id:
type: string
description: Group ID of parent group.
owner_id:
type: string
format: uuid
description: UUID of user that created the group.
metadata:
type: object
description: Arbitrary, object-encoded group's data.
level:
type: integer
description: Level in hierarchy, distance from the root group.
path:
type: string
description: Hierarchy path, concatenated ids of group ancestors.
children:
type: object
# schema: GroupResSchema
created_at:
type: string
description: Datetime of group creation.
updated_at:
type: string
description: Datetime of last group updated.
required:
- id
- name
- owner_id
- description
- level
- path
- created_at
- updated_at
MembersReqSchema:
type: object
properties:
members:
type: array
minItems: 0
uniqueItems: true
items:
type: string
format: uuid | ulid
type:
type: string
description: Type of entity
GroupsPage:
type: object
properties:
groups:
type: array
minItems: 0
uniqueItems: true
items:
$ref: "#/components/schemas/GroupResSchema"
total:
type: integer
description: Total number of items.
level:
type: integer
description: Level of hierarchy up to which groups are fetched.
required:
- groups
- total
- level
MembershipPage:
type: object
properties:
groups:
type: array
minItems: 0
uniqueItems: true
items:
$ref: "#/components/schemas/GroupResSchema"
offset:
type: integer
description: Number of items to skip during retrieval.
limit:
type: integer
description: Maximum number of items to return in one page.
total:
type: integer
description: Total number of items.
required:
- groups
parameters:
Authorization:
name: Authorization
description: User's access token.
in: header
schema:
type: string
format: jwt
required: true
ApiKeyId:
name: id
description: API Key ID.
in: path
schema:
type: string
format: uuid
required: true
GroupId:
name: groupId
description: Group ID.
in: path
schema:
type: string
format: uuid
required: true
MemberId:
name: memberId
description: Member id.
in: path
schema:
type: string
format: uuid | ulid
required: true
Limit:
name: limit
description: Size of the subset to retrieve.
in: query
schema:
type: integer
default: 10
maximum: 100
minimum: 1
required: false
Offset:
name: offset
description: Number of items to skip during retrieval.
in: query
schema:
type: integer
default: 0
minimum: 0
required: false
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
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: {}
Tree:
name: tree
description: Specify type of response, JSON array or tree.
in: query
required: false
schema:
type: boolean
default: false
requestBodies:
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.
token:
type: string
format: jwt
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI"
description: JWT for the entity that's sending Key request.
duration:
type: number
format: integer
example: 23456
description: Number of seconds issued token is valid for.
GroupCreateReq:
description: JSON-formatted document describing group create request.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GroupReqSchema"
GroupUpdateReq:
description: JSON-formatted document describing group create request.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GroupUpdateSchema"
MembersReq:
description: JSON array of member IDs.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MembersReqSchema"
responses:
ServiceError:
description: Unexpected server-side error occurred.
KeyRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/Key"
GroupCreateRes:
description: Group created.
headers:
Location:
content:
text/plain:
schema:
type: string
description: Created group's relative URL.
example: /groups/{groupId}
GroupRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/GroupResSchema"
GroupsPageRes:
description: Group data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/GroupsPage"
MembersRes:
description: Groups data retrieved. Groups assigned to a member.
content:
application/json:
schema:
$ref: "#/components/schemas/MembershipPage"
MembershipPageRes:
description: Groups data retrieved. Groups assigned to a member.
content:
application/json:
schema:
$ref: "#/components/schemas/MembershipPage"
apis/bootstrap.yml
+516
View File
@@ -0,0 +1,516 @@
openapi: 3.0.1
info:
title: Mainflux Bootstrap service
description: HTTP API for managing platform things configuration.
version: "1.0.0"
paths:
/things/configs:
post:
summary: Adds new config
description: |
Adds new config to the list of config owned by user identified using
the provided access token.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/ConfigCreateReq"
responses:
'201':
$ref: "#/components/responses/ConfigCreateRes"
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
get:
summary: Retrieves managed configs
description: |
Retrieves a list of managed configs. Due to performance concerns, data
is retrieved in subsets. The API configs must ensure that the entire
dataset is consumed either by making subsequent requests, or by
increasing the subset size of the initial request.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/State"
- $ref: "#/components/parameters/Name"
responses:
'200':
$ref: "#/components/responses/ConfigListRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/things/configs/{configId}:
get:
summary: Retrieves config info (with channels).
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
responses:
'200':
$ref: "#/components/responses/ConfigRes"
'403':
description: Missing or invalid access token provided.
'404':
description: Config does not exist.
'500':
$ref: "#/components/responses/ServiceError"
put:
summary: Updates config info
description: |
Update is performed by replacing the current resource data with values
provided in a request payload. Note that the owner, ID, external ID,
external key, Mainflux Thing ID and key cannot be changed.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
requestBody:
$ref: "#/components/requestBodies/ConfigUpdateReq"
responses:
'200':
description: Config updated.
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'404':
description: Config does not exist.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
delete:
summary: Removes a Config
description: |
Removes a Config. In case of successful removal the service will ensure
that the removed config is disconnected from all of the Mainflux channels.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
responses:
'204':
description: Config removed.
'400':
description: Failed due to malformed config ID.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/things/configs/certs/{configId}:
patch:
summary: Updates certs
description: |
Update is performed by replacing the current certificate data with values
provided in a request payload.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
requestBody:
$ref: "#/components/requestBodies/ConfigCertUpdateReq"
responses:
'200':
description: Config updated.
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'404':
description: Config does not exist.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
/things/configs/connections/{configId}:
put:
summary: Updates channels the thing is connected to
description: |
Update connections performs update of the channel list corresponding
Thing is connected to.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
requestBody:
$ref: "#/components/requestBodies/ConfigConnUpdateReq"
responses:
'200':
description: Config updated.
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'404':
description: Config does not exist.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
/things/bootstrap/{externalId}:
get:
summary: Retrieves configuration.
description: |
Retrieves a configuration with given external ID and external key.
tags:
- configs
parameters:
- $ref: "#/components/parameters/ConfigAuth"
- $ref: "#/components/parameters/ExternalId"
responses:
'200':
$ref: "#/components/responses/BootstrapConfigRes"
'404':
description: |
Failed to retrieve corresponding config.
'500':
$ref: "#/components/responses/ServiceError"
/things/bootstrap/secure/{externalId}:
get:
summary: Retrieves configuration.
description: |
Retrieves a configuration with given external ID and encrypted external key.
tags:
- configs
parameters:
- $ref: "#/components/parameters/EncConfigAuth"
- $ref: "#/components/parameters/ExternalId"
responses:
'200':
$ref: "#/components/responses/BootstrapConfigRes"
'404':
description: |
Failed to retrieve corresponding config.
'500':
$ref: "#/components/responses/ServiceError"
/things/state/{configId}:
put:
summary: Updates Config state.
description: |
Updating state represents enabling/disabling Config, i.e. connecting
and disconnecting corresponding Mainflux Thing to the list of Channels.
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ConfigId"
requestBody:
$ref: '#/components/requestBodies/ConfigStateUpdateReq'
responses:
'204':
description: Config removed.
'400':
description: Failed due to malformed config's ID.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
components:
schemas:
State:
type: integer
enum: [0, 1]
Config:
type: object
properties:
mainflux_id:
type: string
format: uuid
description: Corresponding Mainflux Thing ID.
mainflux_key:
type: string
format: uuid
description: Corresponding Mainflux Thing key.
mainflux_channels:
type: array
minItems: 0
items:
type: object
properties:
id:
type: string
format: uuid
description: Channel unique identifier.
name:
type: string
description: Name of the Channel.
metadata:
type: object
description: Custom metadata related to the Channel.
external_id:
type: string
description: External ID (MAC address or some unique identifier).
external_key:
type: string
description: External key.
content:
type: string
description: Free-form custom configuration.
state:
$ref: "#/components/schemas/State"
required:
- external_id
- external_key
ConfigList:
type: object
properties:
total:
type: integer
description: Total number of results.
minimum: 0
offset:
type: integer
description: Number of items to skip during retrieval.
minimum: 0
default: 0
limit:
type: integer
description: Size of the subset to retrieve.
maximum: 100
default: 10
configs:
type: array
minItems: 0
uniqueItems: true
items:
$ref: "#/components/schemas/Config"
required:
- configs
BootstrapConfig:
type: object
properties:
mainflux_id:
type: string
format: uuid
description: Corresponding Mainflux Thing ID.
mainflux_key:
type: string
format: uuid
description: Corresponding Mainflux Thing key.
mainflux_channels:
type: array
minItems: 0
items:
type: string
content:
type: string
description: Free-form custom configuration.
client_cert:
type: string
description: Client certificate.
client_key:
type: string
description: Key for the client_cert.
ca_cert:
type: string
description: Issuing CA certificate.
required:
- mainflux_id
- mainflux_key
- mainflux_channels
- content
parameters:
Authorization:
name: Authorization
description: User's access token.
in: header
schema:
type: string
format: jwt
required: true
ConfigAuth:
name: configAuthorization
description: Configuration external key.
in: header
schema:
type: string
required: true
EncConfigAuth:
name: configAuthorization
description: |
Hex-encoded configuration external key encrypted using
the AES algorithm and SHA256 sum of the external key
itself as an encryption key.
in: header
schema:
type: string
required: true
ConfigId:
name: configId
description: Unique Config identifier. It's the ID of the corresponding Thing.
in: path
schema:
type: string
format: uuid
required: true
ExternalId:
name: externalId
description: Unique Config identifier provided by external entity.
in: path
schema:
type: string
required: true
Limit:
name: limit
description: Size of the subset to retrieve.
in: query
schema:
type: integer
default: 10
maximum: 100
minimum: 1
required: false
Offset:
name: offset
description: Number of items to skip during retrieval.
in: query
schema:
type: integer
default: 0
minimum: 0
required: false
State:
name: state
description: A state of items
in: query
schema:
$ref: "#/components/schemas/State"
required: false
Name:
name: name
description: Name of the config. Search by name is partial-match and case-insensitive.
in: query
schema:
type: string
required: false
requestBodies:
ConfigCreateReq:
description: JSON-formatted document describing the new config.
required: true
content:
application/json:
schema:
type: object
properties:
external_id:
type: string
description: External ID (MAC address or some unique identifier).
external_key:
type: string
description: External key.
thing_id:
type: string
description: ID of the corresponding Mainflux Thing.
channels:
type: array
minItems: 0
items:
type: string
content:
type: string
required:
- external_id
- external_key
ConfigUpdateReq:
description: JSON-formatted document describing the updated thing.
content:
application/json:
schema:
type: object
properties:
content:
type: string
name:
type: string
required:
- content
- name
ConfigCertUpdateReq:
description: JSON-formatted document describing the updated thing.
content:
application/json:
schema:
type: object
properties:
client_cert:
type: string
client_key:
type: string
ca_cert:
type: string
ConfigConnUpdateReq:
description: Array if IDs the thing is be connected to.
content:
application/json:
schema:
type: object
properties:
channels:
type: array
minItems: 0
items:
type: string
ConfigStateUpdateReq:
description: Update the state of the Config.
content:
application/json:
schema:
type: object
properties:
state:
$ref: "#/components/schemas/State"
responses:
ConfigCreateRes:
description: Config registered.
headers:
Location:
content:
text/plain:
schema:
type: string
description: Created configuration's relative URL (i.e. /things/configs/{configId}).
ConfigListRes:
description: Data retrieved. Configs from this list don't contain channels.
content:
application/json:
schema:
$ref: "#/components/schemas/ConfigList"
ConfigRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/Config"
BootstrapConfigRes:
description: |
Data retrieved. If secure, a response is encrypted using
the secret key, so the response is in the binary form.
content:
application/json:
schema:
$ref: "#/components/schemas/BootstrapConfig"
ServiceError:
description: Unexpected server-side error occurred.
apis/certs.yml
+155
View File
@@ -0,0 +1,155 @@
openapi: 3.0.1
info:
title: Mainflux Certs service
description: HTTP API for Certs service
version: "1.0.0"
paths:
/certs:
post:
summary: Creates a certificate for thing
description: Creates a certificate for thing
tags:
- Thing to proxy
parameters:
- $ref: "#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/CertReq"
responses:
'201':
description: Created
'400':
description: Failed due to malformed JSON.
'500':
description: Unexpected server-side error ocurred.
/certs/{thingId}:
get:
summary: Retrieves certificates
description: |
Retrieves a certificates for given thing ID .
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ThingID"
responses:
'200':
$ref: "#/components/responses/CertsRes"
'404':
description: |
Failed to retrieve corresponding certificate.
'500':
$ref: "#/components/responses/ServiceError"
/certs/{certId}:
delete:
summary: Revokes certificate
description: |
Revokes a certificates for given cert ID .
tags:
- configs
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/CertID"
responses:
'200':
$ref: "#/components/responses/RevokeRes"
'404':
description: |
Failed to revoke corresponding certificate.
'500':
$ref: "#/components/responses/ServiceError"
components:
parameters:
Authorization:
name: Authorization
description: User's access token. Used instead of credentials in env or config.toml.
in: header
schema:
type: string
required: false
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:
Certs:
type: object
properties:
thing_id:
type: string
format: uuid
description: Corresponding Mainflux 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
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
- days_valid
- key_bits
properties:
thing_id:
type: string
format: uuid
days_valid:
type: string
key_bits:
type: integer
responses:
ServiceError:
description: Unexpected server-side error occurred.
CertsRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/Certs"
RevokeRes:
description: Certificate revoked.
content:
application/json:
schema:
$ref: "#/components/schemas/Revoke"
apis/consumers-notifiers.yml
+206
View File
@@ -0,0 +1,206 @@
openapi: 3.0.1
info:
title: Mainflux Notifiers service
description: HTTP API for Notifiers service.
version: "1.0.0"
paths:
/subscriptions:
post:
summary: Create subscription
description: Creates a new subscription give a topic and contact.
tags:
- notifiers
security:
- Authorization: []
requestBody:
$ref: "#/components/requestBodies/Create"
responses:
"201":
$ref: "#/components/responses/Create"
"400":
description: Failed due to malformed JSON.
"409":
description: Failed due to using an existing topic and contact.
"415":
description: Missing or invalid content type.
"500":
$ref: "#/components/responses/ServiceError"
get:
summary: List subscriptions
description: List subscriptions given list parameters.
tags:
- notifiers
security:
- Authorization: []
parameters:
- $ref: "#/components/parameters/Topic"
- $ref: "#/components/parameters/Contact"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Limit"
responses:
"200":
$ref: "#/components/responses/Page"
"400":
description: Failed due to malformed query parameters.
"403":
description: Missing or invalid access token provided.
"500":
$ref: "#/components/responses/ServiceError"
/subscriptions/{id}:
get:
summary: Get subscription with the provided id
description: Retrieves a subscription with the provided id.
tags:
- notifiers
security:
- Authorization: []
parameters:
- $ref: "#/components/parameters/Id"
responses:
"200":
$ref: "#/components/responses/View"
"403":
description: Missing or invalid access token provided.
"500":
$ref: "#/components/responses/ServiceError"
delete:
summary: Delete subscription with the provided id
description: Removes a subscription with the provided id.
tags:
- notifiers
security:
- Authorization: []
parameters:
- $ref: "#/components/parameters/Id"
responses:
"204":
description: Subscription removed
"403":
description: Missing or invalid access token provided.
"500":
$ref: "#/components/responses/ServiceError"
components:
securitySchemes:
Authorization:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Subscription:
type: object
properties:
id:
type: string
format: ulid
example: 01EWDVKBQSG80B6PQRS9PAAY35
description: ULID id of the subscription.
owner_id:
type: string
format: uuid
example: 18167738-f7a8-4e96-a123-58c3cd14de3a
description: An id of the owner who created subscription.
topic:
type: string
example: topic.subtopic
description: Topic to which the user subscribes.
contact:
type: string
example: user@example.com
description: The contact of the user to which the notification will be sent.
Page:
type: object
properties:
subscriptions:
type: array
minItems: 0
uniqueItems: true
items:
$ref: "#/components/schemas/Subscription"
total:
type: integer
description: Total number of items.
offset:
type: integer
description: Number of items to skip during retrieval.
limit:
type: integer
description: Maximum number of items to return in one page.
parameters:
Id:
name: id
description: Unique identifier.
in: path
schema:
type: string
format: ulid
required: true
Limit:
name: limit
description: Size of the subset to retrieve.
in: query
schema:
type: integer
default: 10
maximum: 100
minimum: 1
required: false
Offset:
name: offset
description: Number of items to skip during retrieval.
in: query
schema:
type: integer
default: 0
minimum: 0
required: false
Topic:
name: topic
description: Topic name.
in: query
schema:
type: string
required: false
Contact:
name: contact
description: Subscription contact.
in: query
schema:
type: string
required: false
requestBodies:
Create:
description: JSON-formatted document describing the new subscription to be created
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
responses:
Create:
description: Created a new subscription.
headers:
Location:
content:
text/plain:
schema:
type: string
description: Created subscription relative URL
example: /subscriptions/{id}
View:
description: View subscription.
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
Page:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/Page"
ServiceError:
description: Unexpected server-side error occurred.
apis/http.yml
+128
View File
@@ -0,0 +1,128 @@
openapi: 3.0.1
info:
title: Mainflux http adapter
description: HTTP API for sending messages through communication channels.
version: "1.0.0"
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/Authorization"
- $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.
'403':
description: Message discarded due to missing or invalid credentials.
'404':
description: Message discarded due to invalid channel id.
'415':
description: Message discarded due to invalid or missing content type.
'500':
description: Unexpected server-side error occurred.
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:
Authorization:
name: Authorization
description: Access token.
in: header
schema:
type: string
format: jwt
required: true
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"
apis/provision.yml
+80
View File
@@ -0,0 +1,80 @@
openapi: 3.0.1
info:
title: Mainflux Provision service
description: HTTP API for Provision service
version: "1.0.0"
paths:
/mapping:
post:
summary: Adds new device to proxy
description: Adds new device to proxy
tags:
- provision
parameters:
- $ref: "#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/ProvisionReq"
responses:
'201':
description: Created
'400':
description: Failed due to malformed JSON.
'403':
description: Unauthorized.
'500':
description: Unexpected server-side error ocurred.
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: "#/components/parameters/Authorization"
responses:
'200':
$ref: "#/components/responses/ProvisionRes"
'403':
description: Unauthorized.
'500':
description: Unexpected server-side error ocurred.
components:
parameters:
Authorization:
name: Authorization
description: User's access token. Used instead of credentials in env or config.toml.
in: header
schema:
type: string
format: jwt
required: false
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:
ProvisionRes:
description: Current mapping JSON representation.
content:
application/json:
schema:
type: object
apis/readers.yml
+215
View File
@@ -0,0 +1,215 @@
openapi: 3.0.1
info:
title: Mainflux reader service
description: HTTP API for reading messages.
version: "1.0.0"
paths:
/channels/{chanId}/messages:
get:
summary: Retrieves messages sent to single channel
description: |
Retrieves a list of messages sent to specific channel. Due to
performance concerns, data is retrieved in subsets. The API readers must
ensure that the entire dataset is consumed either by making subsequent
requests, or by increasing the subset size of the initial request.
tags:
- messages
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/ChanId"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Publisher"
- $ref: "#/components/parameters/Name"
- $ref: "#/components/parameters/Value"
- $ref: "#/components/parameters/BoolValue"
- $ref: "#/components/parameters/StringValue"
- $ref: "#/components/parameters/DataValue"
- $ref: "#/components/parameters/From"
- $ref: "#/components/parameters/To"
responses:
'200':
$ref: "#/components/responses/MessagesPageRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
components:
schemas:
MessagesPage:
type: object
properties:
total:
type: number
description: Total number of items that are present on the system.
offset:
type: number
description: Number of items that were skipped during retrieval.
limit:
type: number
description: Size of the subset that was retrieved.
messages:
type: array
minItems: 0
uniqueItems: true
items:
type: object
properties:
channel:
type: integer
description: Unique channel id.
publisher:
type: integer
description: Unique publisher id.
protocol:
type: string
description: Protocol name.
name:
type: string
description: Measured parameter name.
unit:
type: string
description: Value unit.
value:
type: number
description: Measured value in number.
stringValue:
type: string
description: Measured value in string format.
boolValue:
type: boolean
description: Measured value in boolean format.
dataValue:
type: string
description: Measured value in binary format.
valueSum:
type: number
description: Sum value.
time:
type: number
description: Time of measurement.
updateTime:
type: number
description: Time of updating measurement.
parameters:
Authorization:
name: Authorization
description: Thing access token.
in: header
schema:
type: string
required: true
ChanId:
name: chanId
description: Unique channel identifier.
in: path
schema:
type: string
format: uuid
required: true
Limit:
name: limit
description: Size of the subset to retrieve.
in: query
schema:
type: integer
default: 10
maximum: 100
minimum: 1
required: false
Offset:
name: offset
description: Number of items to skip during retrieval.
in: query
schema:
type: integer
default: 0
minimum: 0
required: false
Publisher:
name: Publisher
description: Unique thing identifier.
in: query
schema:
type: string
format: uuid
required: false
Name:
name: name
description: SenML message name.
in: query
schema:
type: string
required: false
Value:
name: v
description: SenML message value.
in: query
schema:
type: string
required: false
BoolValue:
name: vb
description: SenML message bool value.
in: query
schema:
type: boolean
required: false
StringValue:
name: vs
description: SenML message string value.
in: query
schema:
type: string
required: false
DataValue:
name: vd
description: SenML message data value.
in: query
schema:
type: string
required: false
Comparator:
name: comparator
description: Value comparison operator.
in: query
schema:
type: string
default: eq
enum:
- eq
- lt
- le
- gt
- ge
required: false
From:
name: from
description: SenML message time in nanoseconds (integer part represents seconds).
in: query
schema:
type: number
required: false
To:
name: to
description: SenML message time in nanoseconds (integer part represents seconds).
in: query
schema:
type: number
required: false
responses:
MessagesPageRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/MessagesPage"
ServiceError:
description: Unexpected server-side error occurred.
apis/things.yml
+1015
View File
File diff suppressed because it is too large Load Diff
apis/twins.yml
+367
View File
@@ -0,0 +1,367 @@
openapi: 3.0.1
info:
title: Mainflux twins service
description: HTTP API for managing digital twins and their states.
version: '1.0.0'
paths:
/twins:
post:
summary: Adds new twin
description: |
Adds new twin to the list of twins owned by user identified using
the provided access token.
tags:
- twins
parameters:
- $ref: '#/components/parameters/Authorization'
requestBody:
$ref: "#/components/requestBodies/TwinReq"
responses:
'201':
$ref: "#/components/responses/TwinCreateRes"
'400':
description: Failed due to malformed JSON.
'403':
description: Missing or invalid access token provided.
'415':
description: Missing or invalid content type.
'500':
$ref: '#/components/responses/ServiceError'
get:
summary: Retrieves twins
description: |
Retrieves a list of twins. Due to performance concerns, data
is retrieved in subsets.
tags:
- twins
parameters:
- $ref: '#/components/parameters/Authorization'
- $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.
'403':
description: Missing or invalid access token provided.
'500':
$ref: '#/components/responses/ServiceError'
/twins/{twinID}:
get:
summary: Retrieves twin info
tags:
- twins
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/TwinID'
responses:
'200':
$ref: '#/components/responses/TwinRes'
'400':
description: Failed due to malformed twin's ID.
'403':
description: Missing or invalid access token provided.
'404':
description: Twin does not exist.
'500':
$ref: '#/components/responses/ServiceError'
put:
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/Authorization'
- $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.
'403':
description: Missing or invalid access token provided.
'404':
description: Twin does not exist.
'415':
description: Missing or invalid content type.
'500':
$ref: '#/components/responses/ServiceError'
delete:
summary: Removes a twin
description: Removes a twin.
tags:
- twins
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/TwinID'
responses:
'204':
description: Twin removed.
'400':
description: Failed due to malformed twin's ID.
'403':
description: Missing or invalid access token provided
'404':
description: Twin does not exist.
'500':
$ref: '#/components/responses/ServiceError'
/states/{twinID}:
get:
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/Authorization'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
$ref: '#/components/responses/StatesPageRes'
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'404':
description: Twin does not exist.
'500':
$ref: '#/components/responses/ServiceError'
components:
parameters:
Authorization:
name: Authorization
description: User's access token.
in: header
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
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: Mainflux 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
uniqueItems: true
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 Mainflux 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
uniqueItems: true
items:
$ref: '#/components/schemas/Definition'
metadata:
type: object
description: Arbitrary, object-encoded twin's data.
TwinsPage:
type: object
properties:
twins:
type: array
minItems: 0
uniqueItems: true
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:
twins:
type: array
minItems: 0
uniqueItems: true
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:
- twins
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'
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.
apis/users.yml
+454
View File
@@ -0,0 +1,454 @@
openapi: 3.0.1
info:
title: Mainflux users service
description: HTTP API for managing platform users.
version: "1.0.0"
paths:
/users:
post:
summary: Registers user account
description: |
Registers new user account given email and password. New account will
be uniquely identified by its email address.
tags:
- users
requestBody:
$ref: "#/components/requestBodies/UserCreateReq"
responses:
'201':
$ref: "#/components/responses/UserCreateRes"
'400':
description: Failed due to malformed JSON.
'409':
description: Failed due to using an existing email address.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
get:
summary: Retrieves users
description: |
Retrieves a list of users. 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:
- users
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Metadata"
responses:
'200':
$ref: "#/components/responses/UsersPageRes"
'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"
put:
summary: Updates info on currently logged in user.
description: |
Updates info on currently logged in user. Info is updated using
authorization token and the new received info.
tags:
- users
parameters:
- $ref: "#/components/parameters/Authorization"
requestBody:
$ref: "#/components/requestBodies/UserUpdateReq"
responses:
'200':
description: User updated.
'400':
description: Failed due to malformed JSON.
'404':
description: Failed due to non existing user.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/users/profile:
get:
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:
- Authorization: []
responses:
'200':
$ref: "#/components/responses/UserRes"
'400':
description: Failed due to malformed query parameters.
'403':
description: Missing or invalid access token provided.
'500':
$ref: "#/components/responses/ServiceError"
/groups/{groupId}:
get:
summary: Retrieves users
description: |
Retrieves a list of users that belong to a group. 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:
- users
parameters:
- $ref: "#/components/parameters/Authorization"
- $ref: "#/components/parameters/GroupId"
- $ref: "#/components/parameters/Limit"
- $ref: "#/components/parameters/Offset"
- $ref: "#/components/parameters/Metadata"
responses:
'200':
$ref: "#/components/responses/UsersPageRes"
'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"
/tokens:
post:
summary: User authentication
description: Generates an access token when provided with proper credentials.
tags:
- users
requestBody:
$ref: "#/components/requestBodies/UserCreateReq"
responses:
'201':
description: User authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: Failed due to malformed JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Failed due to using invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
description: Missing or invalid content type.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/ServiceError'
/password/reset-request:
post:
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 reseting password.
'400':
description: Failed due to malformed JSON.
'415':
description: Missing or invalid content type.
'500':
$ref: '#/components/responses/ServiceError'
/password/reset:
put:
summary: User password reset endpoint
description: |
When user gets reset token, after he submited
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.
'415':
description: Missing or invalid content type.
'500':
$ref: '#/components/responses/ServiceError'
/password:
patch:
summary: User password change endpoint
description: |
When authenticated user wants to change password.
tags:
- users
security:
- Authorization: []
requestBody:
$ref: '#/components/requestBodies/PasswordChange'
responses:
'201':
description: User link .
'400':
description: Failed due to malformed JSON.
'415':
description: Missing or invalid content type.
'500':
$ref: "#/components/responses/ServiceError"
components:
securitySchemes:
Authorization:
type: http
scheme: bearer
bearerFormat: jwt
schemas:
Token:
type: object
properties:
token:
type: string
format: jwt
description: Generated access token.
required:
- token
UserReqObj:
type: object
properties:
email:
type: string
format: email
example: "test@example.com"
description: User's email address will be used as its unique identifier
password:
type: string
format: password
minimum: 8
description: Free-form account password used for acquiring auth token(s).
required:
- email
- password
User:
type: object
properties:
id:
type: string
format: uuid
example: 18167738-f7a8-4e96-a123-58c3cd14de3a
description: User unique identifier.
email:
type: string
format: email
example: "test@example.com"
description: User's email address will be used as its unique identifier.
metadata:
type: object
description: Arbitrary, object-encoded user's data.
UsersPage:
type: object
properties:
things:
type: array
minItems: 0
uniqueItems: true
items:
$ref: "#/components/schemas/User"
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:
- things
UserMetadata:
type: object
properties:
metadata:
type: object
description: Arbitrary, object-encoded user's data.
Error:
type: object
properties:
error:
type: string
description: Error message
parameters:
Authorization:
name: Authorization
description: User's access token.
in: header
schema:
type: string
format: jwt
required: true
Referer:
name: Referer
description: Host being sent by browser.
in: header
schema:
type: string
required: true
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
UserID:
name: userId
description: Unique user identifier.
in: path
schema:
type: string
format: uuid
required: true
GroupId:
name: groupId
description: Unique group identifier.
in: path
schema:
type: string
format: ulid
required: true
Limit:
name: limit
description: Size of the subset to retrieve.
in: query
schema:
type: integer
default: 10
maximum: 100
minimum: 1
required: false
Offset:
name: offset
description: Number of items to skip during retrieval.
in: query
schema:
type: integer
default: 0
minimum: 0
required: false
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 of user to be update
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserMetadata"
RequestPasswordReset:
description: Initiate password request procedure.
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: User email.
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.
minimum: 8
confirm_password:
type: string
format: password
description: New confirmation password.
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
description: New password.
old_password:
type: string
format: password
description: Old password.
responses:
UserCreateRes:
description: Registered new user.
headers:
Location:
content:
text/plain:
schema:
type: string
format: url
description: Registered user relative URL.
example: /users/{userId}
UserRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/User"
UsersPageRes:
description: Data retrieved.
content:
application/json:
schema:
$ref: "#/components/schemas/UsersPage"
ServiceError:
description: Unexpected server-side error occurred.
favicon-16x16.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 665 B

favicon-32x32.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 628 B

index.html
+65
View File
@@ -0,0 +1,65 @@
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
<link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body
{
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
<script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
"dom_id": "#swagger-ui",
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout",
configUrl: "swagger-config.json",
})
// End Swagger UI call region
window.ui = ui;
};
</script>
</body>
</html>
index.html.gz
BIN
View File
Binary file not shown.
oauth2-redirect.html
+75
View File
@@ -0,0 +1,75 @@
<!doctype html>
<html lang="en-US">
<head>
<title>Swagger UI: OAuth2 Redirect</title>
</head>
<body>
<script>
'use strict';
function run () {
var oauth2 = window.opener.swaggerUIRedirectOauth2;
var sentState = oauth2.state;
var redirectUrl = oauth2.redirectUrl;
var isValid, qp, arr;
if (/code|token|error/.test(window.location.hash)) {
qp = window.location.hash.substring(1);
} else {
qp = location.search.substring(1);
}
arr = qp.split("&");
arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
qp = qp ? JSON.parse('{' + arr.join() + '}',
function (key, value) {
return key === "" ? value : decodeURIComponent(value);
}
) : {};
isValid = qp.state === sentState;
if ((
oauth2.auth.schema.get("flow") === "accessCode" ||
oauth2.auth.schema.get("flow") === "authorizationCode" ||
oauth2.auth.schema.get("flow") === "authorization_code"
) && !oauth2.auth.code) {
if (!isValid) {
oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "warning",
message: "Authorization may be unsafe, passed state was changed in server Passed state wasn't returned from auth server"
});
}
if (qp.code) {
delete oauth2.state;
oauth2.auth.code = qp.code;
oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
} else {
let oauthErrorMsg;
if (qp.error) {
oauthErrorMsg = "["+qp.error+"]: " +
(qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
(qp.error_uri ? "More info: "+qp.error_uri : "");
}
oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "error",
message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server"
});
}
} else {
oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
}
window.close();
}
window.addEventListener('DOMContentLoaded', function () {
run();
});
</script>
</body>
</html>
oauth2-redirect.html.gz
BIN
View File
Binary file not shown.
swagger-config.json
+1
View File
@@ -0,0 +1 @@
{"urls":[{"name":"auth.yml","url":"apis/auth.yml"},{"name":"bootstrap.yml","url":"apis/bootstrap.yml"},{"name":"certs.yml","url":"apis/certs.yml"},{"name":"consumers-notifiers.yml","url":"apis/consumers-notifiers.yml"},{"name":"http.yml","url":"apis/http.yml"},{"name":"provision.yml","url":"apis/provision.yml"},{"name":"readers.yml","url":"apis/readers.yml"},{"name":"things.yml","url":"apis/things.yml"},{"name":"twins.yml","url":"apis/twins.yml"},{"name":"users.yml","url":"apis/users.yml"}]}
swagger-ui-bundle.js
+3
View File
File diff suppressed because one or more lines are too long
swagger-ui-bundle.js.gz
BIN
View File
Binary file not shown.
swagger-ui-bundle.js.map
+1
View File
File diff suppressed because one or more lines are too long
swagger-ui-es-bundle-core.js
+3
View File
File diff suppressed because one or more lines are too long
swagger-ui-es-bundle-core.js.gz
BIN
View File
Binary file not shown.
swagger-ui-es-bundle-core.js.map
+1
View File
File diff suppressed because one or more lines are too long
swagger-ui-es-bundle.js
+3
View File
File diff suppressed because one or more lines are too long
swagger-ui-es-bundle.js.gz
BIN
View File
Binary file not shown.
swagger-ui-es-bundle.js.map
+1
View File
File diff suppressed because one or more lines are too long
swagger-ui-standalone-preset.js
+3
View File
File diff suppressed because one or more lines are too long
swagger-ui-standalone-preset.js.gz
BIN
View File
Binary file not shown.
swagger-ui-standalone-preset.js.map
+1
View File
File diff suppressed because one or more lines are too long
swagger-ui.css
+4
View File
File diff suppressed because one or more lines are too long
swagger-ui.css.gz
BIN
View File
Binary file not shown.
swagger-ui.css.map
+1
View File
File diff suppressed because one or more lines are too long
swagger-ui.js
+3
View File
File diff suppressed because one or more lines are too long
swagger-ui.js.gz
BIN
View File
Binary file not shown.
swagger-ui.js.map
+1
View File
File diff suppressed because one or more lines are too long