macao-pos/README.md
crudo 6b159b6eda Switch from Flask to aiohttp.
This repository now provides the REST API only.

Implemented:
 * Authorization

Need improvement:
 * Product listing

Missing:
 * Selling
2017-09-25 19:38:45 +02:00

193 lines
4.2 KiB
Markdown

# macao-pos
## Installation
The only requirements are Python 3 and virtualenv as you're going to install all
the modules through pip.
If you're using MySQL or PostgreSQL create now a new user and database. You can
also use SQLite for testing purposes.
```
cd /var/www
git clone ...
cd macao-pos
virtualenv -p python3 env
source env/bin/activate
pip install -r requirements.txt
```
Now you need to configure this software. Inside `doc/` you'll find some
examples. The default path for configurations in `conf/` but you can also use
`~/.config/pos`, `/usr/local/etc/pos` and `/etc/pos` that will be checked in
this order.
For a testing environment you can just do:
```
mkdir conf
cp docs/config_core/core_debug_sqlite.ini conf/core.ini
cp docs/config_logging/logging_debug.yaml conf/logging.yaml
```
and you're ready to go.
For a production environment:
```
cd /var/www/macao-pos
mkdir conf
cp docs/config_core/core_production_mysql.ini conf/core.ini
cp docs/config_logging/logging_production.yaml conf/logging.yaml
```
and then edit the conf/core.ini file to adjust the database params. Don't forget
to change the SECRET_KEY value (`openssl rand -hex 32` will help you).
If you want to change the log file path open your `conf/logging.yaml` and
change the `filename` field of the `file` entry inside the `handlers` category.
### Building the database
You also need to add some entries to the database.
First of all add a new user. Get inside the virtualenv and then just do:
```
python3 cli.py user add username password
```
Add some categories with:
```
python3 cli.py category add "Birra"
python3 cli.py category add "Super"
python3 cli.py category add "Altro"
```
Add some products with:
```
python3 cli.py product add -c 1 "Birra media" 3
python3 cli.py product add -c 1 "Birra grande" 4
python3 cli.py product add -c 2 "Vino" 4
python3 cli.py product add -c 2 "Cocktail" 5
python3 cli.py product add -c 2 "Amaro" 2
python3 cli.py product add -c 3 "Acqua" 0.5
```
And finally add and event you can play with:
```
python3 cli.py event add "My party" "2017-03-19 22:00" "2017-03-22 07:00"
```
## Running
You can run this software within the virtualenv with:
```
python3 web.py
```
## REST API
### Authentication
* **URL**: `/api/token`
* **Method**: `POST`
* **Success response**:
* **Code**: 200
* **Content**:
```
{
"token": "3ea90c63-4b92-465e-bee8-018a4c569252",
"created_at": "2017-09-25T18:50:38.620881",
"expires_at": "2017-09-25T18:50:38.620881"
}
```
* **Error response**:
* ***Malformed request***
* **Code**: 400
* **Content**:
```
{
"err": "malformed_request",
"msg": "Missing username and/or password keys."
}
```
* ***Invalid credentials***
* **Code**: 400
* **Content**:
```
{
"err": "invalid_credentials"
}
```
* **Sample call**:
```
curl -X POST \
-H "Accept: application/json" \
-d '{"username": "gino", "password": "paoli"}' \
"http://127.0.0.1:8080/api/token"
```
### Logout
* **URL**: `/api/token`
* **Method**: `DELETE`
* **Success response**:
* **Code**: 200
* **Content**:
```
{}
```
* **Error response**:
* ***Malformed request***
* **Code**: 400
* **Content**:
```
{
"err": "malformed_request",
"msg": "Missing Authorization header."
}
```
* ***Unauthorizred***
* **Code**: 401
* **Content**:
```
{
"err": "unauthorized",
"msg": "The token is not valid."
}
```
* ***Forbidden***
* **Code**: 403
* **Content**:
```
{
"err": "forbidden",
"msg": "The token has expired."
}
```
* **Sample call**:
```
curl -X DELETE \
-H "Authorization: 3ea90c63-4b92-465e-bee8-018a4c569252" \
"http://127.0.0.1:8080/api/token"
```
## Contributing
Before pushing any commit make sure flake8 doesn't complain running:
```
flake8 web.py cli.py pos/*.py
```
1. Clone this repository
2. Create a new branch
3. Make your patch. Split it in different commits if it's huge
4. Fork this repo
5. Push your branch to your fork
6. Issue a pull request