forked from crudo/macao-pos
crudo
6b159b6eda
This repository now provides the REST API only. Implemented: * Authorization Need improvement: * Product listing Missing: * Selling
193 lines
4.2 KiB
Markdown
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
|