university-final-iot-backend/app/swagger/template.yaml

547 lines
11 KiB
YAML
Raw Normal View History

2018-05-07 14:13:07 +00:00
---
servers:
- url: https://final-iot-backend.herokuapp.com/
description: Heroku deployed app for production usage
- url: https://final-iot-backend-staging.herokuapp.com/
description: Heroku staging app for pre-release testing
- url: https://final-iot-backend-test.herokuapp.com/
description: Heroku test app
2018-05-07 14:13:07 +00:00
basePath: ""
definitions:
2018-09-23 11:56:41 +00:00
genericname:
type: string
description: name
2018-09-23 16:56:29 +00:00
example: name
2018-09-23 11:56:41 +00:00
2018-05-07 14:13:07 +00:00
username:
type: string
description: User's name in the system
2018-09-23 16:56:29 +00:00
example: user_name
2018-05-07 14:13:07 +00:00
2018-05-08 14:45:09 +00:00
id:
type: integer
description: ID
2018-09-23 16:56:29 +00:00
example: 1
2018-05-08 14:45:09 +00:00
datetime:
type: string
description: Time
2018-09-23 16:56:29 +00:00
example: 2018-09-19T17:50:24+00:00
2018-05-08 14:45:09 +00:00
2018-09-23 16:44:32 +00:00
timestamp:
type: integer
description: Time
2018-09-23 16:56:29 +00:00
example: 1537379424
2018-09-23 16:44:32 +00:00
2018-09-17 22:51:26 +00:00
devicetypename:
type: string
description: Name of device type
default: STANDARD
2018-09-23 16:56:29 +00:00
example: STANDARD
2018-09-17 22:51:26 +00:00
2018-05-08 14:45:09 +00:00
devicename:
type: string
description: Name of device
2018-09-23 16:56:29 +00:00
example: Temperature device
2018-05-08 14:45:09 +00:00
devicetype:
2018-09-23 16:44:32 +00:00
type: integer
2018-05-08 14:45:09 +00:00
description: Type of device
2018-09-23 16:56:29 +00:00
example: 1
2018-05-08 14:45:09 +00:00
2018-05-07 14:13:07 +00:00
email:
type: string
format: email
description: User's registered email
2018-09-23 16:56:29 +00:00
example: user@mail.com
2018-05-07 14:13:07 +00:00
password:
type: string
format: password
description: User's password
2018-09-23 16:56:29 +00:00
example: TestPassword1234
2018-05-07 14:13:07 +00:00
status:
type: string
description: Status of request
2018-09-23 16:56:29 +00:00
example: error
2018-05-07 14:13:07 +00:00
message:
type: string
description: Descriptive message
2018-09-23 16:56:29 +00:00
example: Long message
2018-05-07 14:13:07 +00:00
2018-09-19 22:23:22 +00:00
configuration:
type: string
description: Configuration
2018-09-23 16:56:29 +00:00
example: {}
2018-09-19 22:23:22 +00:00
2018-09-19 23:42:37 +00:00
dashboarddata:
2018-09-23 12:07:36 +00:00
type: object
2018-09-19 23:42:37 +00:00
description: Dashboard data
2018-09-23 16:56:29 +00:00
example: {}
2018-09-19 23:42:37 +00:00
2018-10-22 21:54:31 +00:00
filters:
type: object
description: Dashboard data
example: {}
charttype:
type: string
description: Type of chart
example: line
2018-10-29 21:47:03 +00:00
secret:
type: string
description: Secret key
example: Ranom-Key123
hashalgorithm:
type: string
description: Hashing algorithm used
example: sha512
2018-05-07 14:13:07 +00:00
Credentials:
type: object
required:
- username
- password
properties:
username:
$ref: '#/definitions/username'
password:
$ref: '#/definitions/password'
User:
type: object
required:
- username
- password
- email
properties:
username:
$ref: '#/definitions/username'
password:
$ref: '#/definitions/password'
email:
$ref: '#/definitions/email'
2018-09-23 11:56:41 +00:00
Role:
type: object
required:
- id
- display_name
- permissions
properties:
id:
$ref: '#/definitions/id'
display_name:
$ref: '#/definitions/genericname'
permissions:
type: array
items:
$ref: '#definitions/genericname'
2018-05-08 14:45:09 +00:00
Recording:
type: object
required:
- recorded_at
- record_type
- record_value
properties:
recorded_at:
$ref: '#/definitions/datetime'
record_type:
$ref: '#/definitions/id'
record_value:
type: float
2018-05-08 14:45:09 +00:00
description: Value of the recording
example: 25.0
2018-05-08 14:45:09 +00:00
2018-10-30 19:55:35 +00:00
Query:
type: object
required:
- selections
- filters
- groups
2018-10-30 23:03:25 +00:00
- orders
2018-10-30 19:55:35 +00:00
properties:
selections:
type: object
description: SELECT part of query - columns to select and aggregate
example: { "record_value": "sum" }
filters:
type: object
description: WHERE part of query (filters) - All of them are combined with AND
example: { "record_value": { "$gt": "300", "$lt": "1000" } }
groups:
type: object
description: GROUP BY part of query
example: { "recorded_at": "year" }
2018-10-30 23:03:25 +00:00
orders:
type: object
description: ORDER BY part of query
example: { "group_recorded_at": "asc" }
2018-10-30 19:55:35 +00:00
2018-09-23 16:44:32 +00:00
RecordingCreation:
type: object
required:
- recorded_at
- record_type
- record_value
properties:
recorded_at:
$ref: '#/definitions/timestamp'
record_type:
$ref: '#/definitions/id'
record_value:
type: float
2018-09-23 16:44:32 +00:00
description: Value of the recording
example: 25.0
2018-09-23 16:44:32 +00:00
2018-09-17 22:51:26 +00:00
DeviceType:
type: object
required:
- id
- name
properties:
id:
$ref: '#/definitions/id'
name:
$ref: '#/definitions/devicetypename'
2018-05-08 14:45:09 +00:00
Device:
type: object
required:
- id
- name
2018-09-17 22:51:26 +00:00
- device_type
2018-11-03 14:47:38 +00:00
- created_at
- modified_at
2018-05-08 14:45:09 +00:00
properties:
id:
$ref: '#/definitions/id'
name:
$ref: '#/definitions/devicename'
2018-09-17 22:51:26 +00:00
device_type:
$ref: '#/definitions/DeviceType'
2018-11-03 14:47:38 +00:00
created_at:
$ref: '#/definitions/datetime'
modified_at:
$ref: '#/definitions/datetime'
2018-05-08 14:45:09 +00:00
2018-11-01 00:45:14 +00:00
DeviceShareTokenCreation:
type: object
required:
- access_level_id
properties:
access_level_id:
$ref: '#/definitions/id'
account_id:
$ref: '#/definitions/id'
DeviceShareToken:
type: object
required:
- token
- activation_url
properties:
token:
type: string
description: Activation token used to gain access to shared device
example: idjsfodsfmskdf12312nkVDSFSDFS
activation_url:
type: string
description: Activation url using token
example: https://etf-iot.com/api/v1/devices/123/share/activation/idjsfodsfmskdf12312nkVDSFSDFS
2018-09-19 22:23:22 +00:00
DeviceWithConfig:
type: object
required:
- id
- name
- device_type
- configuration
properties:
id:
$ref: '#/definitions/id'
name:
$ref: '#/definitions/devicename'
device_type:
$ref: '#/definitions/DeviceType'
configuration:
$ref: '#/definitions/configuration'
2018-10-29 21:47:03 +00:00
DeviceSecretInfo:
type: object
required:
- device_secret
- secret_algorithm
properties:
device_secret:
$ref: '#/definitions/secret'
secret_algorithm:
$ref: '#/definitions/hashalgorithm'
2018-09-19 21:04:49 +00:00
DeviceCreation:
type: object
required:
- name
- device_type_id
properties:
name:
$ref: '#/definitions/devicename'
device_type_id:
$ref: '#/definitions/id'
2018-09-19 23:42:37 +00:00
Dashboard:
type: object
required:
- id
2018-10-22 19:29:20 +00:00
- active
2018-09-19 23:42:37 +00:00
- dashboard_data
2018-10-22 19:29:20 +00:00
- name
2018-09-19 23:42:37 +00:00
properties:
id:
$ref: '#/definitions/id'
dashboard_data:
$ref: '#/definitions/dashboarddata'
2018-10-22 21:54:31 +00:00
active:
type: boolean
name:
type: '#definitions/devicename'
2018-09-19 23:42:37 +00:00
DashboardCreation:
type: object
required:
2018-10-15 17:51:51 +00:00
- active
2018-09-19 23:42:37 +00:00
- dashboard_data
2018-10-22 19:29:20 +00:00
- name
2018-09-19 23:42:37 +00:00
properties:
dashboard_data:
$ref: '#/definitions/dashboarddata'
2018-10-15 17:51:51 +00:00
active:
type: boolean
2018-10-22 21:54:31 +00:00
name:
ref: '#definitions/genericname'
2018-11-04 12:38:53 +00:00
VersionInfo:
type: object
required:
- name
- build_number
properties:
name:
type: string
description: Version name following semantic versioning
example: 0.4.3
build_number:
type: string
description: Number of current build/release
example: v72
FrontendInfo:
type: object
required:
- url
properties:
url:
type: string
description: URL of frontend used with this backend.
example: https://iot-frontend-app.herokuapp.com
EmailConfigInfo:
type: object
required:
- mailer_account
- contact_accounts
properties:
mailer_account:
type: string
description: Account used to send emails to users
example: final.iot.backend.mailer@gmail.com
contact_accounts:
type: string
description: Emails used to contact developers
example: []
AppConfig:
type: object
required:
- version
- frontend
- email
properties:
version:
$ref: '#/definitions/VersionInfo'
frontend:
$ref: '#/definitions/FrontendInfo'
email:
$ref: '#/definitions/EmailConfigInfo'
2018-11-04 12:16:50 +00:00
MqttBroker:
type: object
required:
- url
- port
properties:
url:
type: string
description: Url of the used MQTT broker
example: broker.hivemq.com
port:
type: number
description: Port of the used MQTT broker
example: 1883
MqttEndpoint:
type: object
required:
- topic
- description
- body_example
properties:
topic:
type: string
description: Topic of this endpoint
example: device/<device_id>
description:
type: string
description: Description of usage of this endpoint
example: Used to send data to devices
body_example:
type: object
description: Example of body of messages used on this endpoint
example: {}
MqttConfig:
type: object
required:
- broker
- endpoints
properties:
broker:
$ref: '#/definitions/MqttBroker'
endpoints:
type: array
items:
$ref: '#/definitions/MqttEndpoint'
2018-10-22 21:54:31 +00:00
Widget:
type: object
required:
- id
- dashboard_id
- device_id
2018-11-03 14:47:38 +00:00
- name
2018-10-22 21:54:31 +00:00
- width
- height
- x
- y
- chart_type
- filters
properties:
id:
$ref: '#/definitions/id'
dashboard_id:
$ref: '#/definitions/id'
device_id:
$ref: '#/definitions/id'
2018-11-03 14:47:38 +00:00
name:
$ref: '#/definitions/genericname'
2018-10-22 21:54:31 +00:00
width:
$ref: '#/definitions/id'
height:
$ref: '#/definitions/id'
x:
$ref: '#/definitions/id'
y:
$ref: '#/definitions/id'
chart_type:
$ref: '#/definitions/charttype'
filters:
$ref: '#/definitions/filters'
WidgetCreation:
type: object
required:
- device_id
- width
- height
- x
- y
- chart_type
- filters
properties:
device_id:
$ref: '#/definitions/id'
width:
$ref: '#/definitions/id'
height:
$ref: '#/definitions/id'
x:
$ref: '#/definitions/id'
y:
$ref: '#/definitions/id'
chart_type:
$ref: '#/definitions/charttype'
filters:
$ref: '#/definitions/filters'
2018-09-19 23:42:37 +00:00
UnauthorizedError:
type: object
required:
- status
- message
properties:
status:
$ref: '#/definitions/status'
2018-09-23 16:56:29 +00:00
example: error
message:
$ref: '#/definitions/message'
2018-09-23 16:56:29 +00:00
example: Unauthorized
2018-05-07 14:13:07 +00:00
Error:
type: object
required:
- status
- message
properties:
status:
$ref: '#/definitions/status'
2018-09-23 16:56:29 +00:00
example: error
2018-05-07 14:13:07 +00:00
message:
$ref: '#/definitions/message'
2018-09-23 16:56:29 +00:00
example: Error message
2018-05-07 14:13:07 +00:00
securityDefinitions:
Bearer:
type: apiKey
name: Authorization
in: header
description: |
For accessing the API a valid JWT token must be passed in all the queries in
the 'Authorization' header as Bearer token.
A valid JWT token is generated by the API and returned as answer of a call
to the route /login giving a valid user & password.
The following syntax must be used in the 'Authorization' header :
Bearer xxxxxx.yyyyyyy.zzzzzz
security:
- Bearer: []
2018-05-07 14:13:07 +00:00
info:
description: Python (Flask) backend for IoT sysyem made for master's degree final project
title: IoT Backend
2018-09-23 16:44:32 +00:00
version: 0.1.0
2018-05-07 14:13:07 +00:00
swagger: '2.0'