Commit f5c15c1e authored by antoine masson's avatar antoine masson
Browse files

beta-2

parent b4d650f2
# EAWAG Swing Docs
# EAWAG Survey Docs
This documentation is compiled and added into `/admin/docs` in the webapp
## Commands
## Principle
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
This documentation is generated using [Mkdocs](https://www.mkdocs.org/). It converts markdown files into a static html website
## Project layout
## Commands
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
* to preview the documentation : ```mkdocs serve```
* to build the documentation : ```mkdocs build```
* to generate the ```requirements.txt``` file : ```pip freeze > requirements.txt```
## Mkdocs
This documentation uses mkdocs
## Install the necessary packages to compile the documentation
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
1. create a directory and go inside it
1. ```python -m venv env```
1. ```pip install -r requirements.txt```
1. ```source ./env/bin/activate```
......@@ -5,22 +5,708 @@ authors:
- Antoine Masson
---
## Authentication
Can be
* ```none``` : accessible to public
* ```CLIENT``` : accessible with a token token
* ```ADMIN``` : accessible with an admin token
Authentication is done by adding a http Authorization bearer header with the token ```config.headers['Authorization'] = `Bearer ${ token }```.
## General
* Inputs are x-www-form-urlencoded in body
### root /
* Action : Return the version of the API
* URL : ```/```
* Method : ```GET```
* Input : ```none```
* Auth : ```none```
* Output : ```JSON```
Output:
```javascript
{
message: "API EAWAG Version 1.0.7",
status: "OK"
}
```
## Survey Commands
### Admin side
#### List all surveys
#### Create a survey
#### Get a survey
#### Download a survey
#### Update a survey
#### Enable a survey
#### Disable a survey
#### Delete a survey
#### Update global options
#### Get global options
#### Drop survey table
### Client side
#### Get survey key
#### Get survey info
#### Get language variables
### Language Management Admin side
#### List languages
#### Create a language
#### Update a language
#### Delete a language
#### Save langdef definition file
#### Load langdef definition file
#### Download language definition
#### Upload language definition
### Variables Template Management Admin side
#### List variable
#### Create a variable
#### Update a variable
#### Delete a variable
#### Save langtrans definition file
#### Load langtrans definition file
#### Download variables definition
#### Upload variables definition
## Token Commands
### Admin side
#### Get token list
* Action : Get array of all token
* URL : ```/tokens/all```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
tokens: [
{
enable: true,
test: false,
access: false,
token: "test0",
survey_id: "603669e6778980752582f5b3",
status: "connected",
comments: null,
createdAt: "2021-02-28T12:41:05.646Z",
updatedAt: "2021-04-08T20:10:10.358Z",
answers: {
selectlanguage: "ENGLISH",
agreedata: false,
lastupdate: 1617912610324,
lasturl: "/survey/welcome.htm"
},
id: "<tokenid>"
},
...
],
message: "",
status: "OK"
}
```
#### Create Token
* Action : Create a new token
* URL : ```/tokens/register```
* Method : ```POST```
* Input : [token model](./models/token.md)
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
token:{
enable: true,
test: false,
access: false,
token: "test0",
survey_id: "603669e6778980752582f5b3",
status: "connected",
comments: null,
createdAt: "2021-02-28T12:41:05.646Z",
updatedAt: "2021-04-08T20:10:10.358Z",
id: "<tokenid>"
},
message: "Token created",
status: "OK"
}
```
#### Get a Token
* Action : Get token info
* URL : ```/tokens/token/<tokenid>```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
token:{
enable: true,
test: false,
access: false,
token: "test0",
survey_id: "603669e6778980752582f5b3",
status: "connected",
comments: null,
createdAt: "2021-02-28T12:41:05.646Z",
updatedAt: "2021-04-08T20:10:10.358Z",
answers: {
selectlanguage: "ENGLISH",
agreedata: false,
lastupdate: 1617912610324,
lasturl: "/survey/welcome.htm"
},
id: "<tokenid>"
},
message: "",
status: "OK"
}
```
#### Modify token
* Action : Modify a token
* URL : ```/tokens/token/<tokenid>```
* Method : ```PUT```
* Input : [token model](./models/token.md)
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
id : "<tokenid>"
message: "Token modified",
status: "OK"
}
```
#### Delete token
* Action : Delete a token
* URL : ```/tokens/token/<tokenid>```
* Method : ```DELETE```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
id : "<tokenid>"
message: "Token successfully deleted",
status: "OK"
}
```
#### Get token of a survey
* Action : Get test token of survey
* URL : ```/tokens/survey/<surveyid>```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
tokens: [
{
enable: true,
test: false,
access: false,
token: "test0",
survey_id: "603669e6778980752582f5b3",
status: "connected",
comments: null,
createdAt: "2021-02-28T12:41:05.646Z",
updatedAt: "2021-04-08T20:10:10.358Z",
answers: {
selectlanguage: "ENGLISH",
agreedata: false,
lastupdate: 1617912610324,
lasturl: "/survey/welcome.htm"
},
id: "<tokenid>"
},
...
],
message: "",
status: "OK"
}
```
#### Get test token of a survey
* Action : Get test token of survey
* URL : ```/tokens/survey/<surveyid>/test```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
tokens:{
enable: true,
test: true,
access: false,
token: "0b459a6fba",
survey_id: "60361c6ac9e7196193adb9dd",
status: "new",
comments: "Automatically created by API",
createdAt: "2021-02-24T09:29:14.853Z",
updatedAt: "2021-02-24T09:29:14.853Z",
id: "<tokenid>"
},
message: "",
status: "OK"
}
```
#### Download JSON of token for given survey
* Action : Get test token of survey
* URL : ```/tokens/downjson/<surveyid>```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```File```
#### Download CSV conversion of token for given survey
* Action : Get test token of survey
* URL : ```/tokens/downcsv/<surveyid>```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```File```
### Client side
#### Login
* Action : Login admin user
* URL : ```/tokens/login```
* Method : ```POST```
* Input : ```token ```
* Auth : ```none```
* Output : ```JSON```
Output:
```javascript
{
token: "...",
message: "Succeeded Login",
status: "OK"
}
```
#### Access login
* Action : Create a new token with direct access
* URL : ```/tokens/access```
* Method : ```POST```
* Input : ```survey_id```, ```token```
* Auth : ```none```
* Output : ```JSON```
!!! note
Only accessible when access token is enabled on the survey
Output:
```javascript
{
token: "...",
message: "Succeeded Login",
status: "OK"
}
```
#### Get Me
* Action : give info about used token
* URL : ```/tokens/me```
* Method : ```GET```
* Input : ```none```
* Auth : ```CLIENT```
* Output : ```JSON```
Output:
```javascript
{
user: {
id: "603b8f616fbde221723a7e42",
token: "test0",
survey_id: "603669e6778980752582f5b3",
status: "connected",
access: false,
admin: false,
test: false,
answers: {
selectlanguage: "ENGLISH",
agreedata: false,
lastupdate: 1617912610324,
lasturl: "/survey/welcome.htm",
presurvey: {},
postsurvey: {},
rational: {}
},
iat: 1619461489,
exp: 1619547889
},
message: "",
status: "OK"
}
```
#### Update Me status
* Action : update status of used token
* URL : ```/tokens/me/status```
* Method : ```PUT```
* Input : ```status```
* Auth : ```CLIENT```
* Output : ```JSON```
Output:
```javascript
{
message: "Token status modified",
status: "OK"
}
```
#### Update Answer
* Action : update answers of used token
* URL : ```/tokens/me/answers```
* Method : ```PUT```
* Input : ```answers``` [See answers/result](../survey/results.md)
* Auth : ```CLIENT```
* Output : ```JSON```
Output:
```javascript
{
message: "Token answers modified",
status: "OK"
}
```
#### Get Answers
* Action : get answers of used token
* URL : ```/tokens/me/answers```
* Method : ```GET```
* Input : ```none```
* Auth : ```CLIENT```
* Output : ```JSON```
Output:
```javascript
{
answers: {
selectlanguage: "ENGLISH",
agreedata: false,
lastupdate: 1617912610324,
lasturl: "/survey/welcome.htm",
presurvey: {},
postsurvey: {},
rational: {}
},
message: "",
status: "OK"
}
```
## User commands
### Admin side
#### Get user list
* Action : Get array of all admin user
* URL : ```/adminusers/all```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
users: [{
admin: true,
enable: true,
username: "...@youmi-lausanne.ch",
lastname: "masson",
firstname: "antoine",
createdAt: "2021-04-26T13:52:35.630Z",
updatedAt: "2021-04-26T13:52:35.630Z",
id: "<userid>
},
...
],
message: "",
status: "OK"
}
```
#### Login
* Action : Login admin user
* URL : ```/adminusers/login```
* Method : ```POST```
* Input : ```username , password```
* Auth : ```none```
* Output : ```JSON```
Output:
```javascript
{
token: "...",
message: "Succeeded Login",
status: "OK"
}
```
#### Register
* Action : Create a new admin user
* URL : ```/adminusers/register```
* Method : ```POST```
* Input : [user model](./models/users.md)
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
token: "...",
user: {
admin: true,
enable: true,
username: "...@youmi-lausanne.ch",
lastname: "masson",
firstname: "antoine",
createdAt: "2021-04-26T13:52:35.630Z",
updatedAt: "2021-04-26T13:52:35.630Z",
id: "<userid>
},
message: "User created",
status: "OK"
}
```
#### Get Me
* Action : give info about used token
* URL : ```/adminusers/me```
* Method : ```GET```
* Input : ```none```
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
user: {
id: "<userid>",
username: "...@youmi-lausanne.ch",
firstname: "antoine",
lastname: "masson",
comments: null,
admin: true,
iat: 1619445055,
exp: 1619531455
},
message: "",
status: "OK"
}
```
#### Modify Me
* Action : modify info about used token
* URL : ```/adminusers/me```
* Method : ```PUT```
* Input : [user model](./models/users.md)
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{
message: "User modified",
status: "OK"
}
```
#### Modify a user
* Action : Modify an admin user
* URL : ```/adminusers/user/<userid>```
* Method : ```PUT```
* Input : [user model](./models/users.md)
* Auth : ```ADMIN```
* Output : ```JSON```
Output:
```javascript
{