REST-API UNIVERSITY
This application is designed to manage the data of the university’s education department.
Project uses:
Flask (flask-restful)
SqlAlchemy (flask-sqlalchemy)
Alembic (flask-migrate)
Marshmallow (flask-marshmallow)
Swagger (flasgger)
Pytest
PostgreSQL
Docker (docker-compose)
Nginx
Task description:
To get rest-api docs, visit http://0.0.0.0:8080/api/v1/docs
Main stack:
- Create an application that inserts/updates/deletes data in the database using
sqlalchemy
andflask rest framework
; - Use
PostgreSQL
DB; - Migrations must be done with
flask-migrate
; - Serialization and deserialization should be done with
marshmallow
orflask-marshmallow
;
Models:
Models should have the following fields:
-
GroupModel:
- name
-
StudentModel:
- group_id
- first_name
- last_name
-
CourseModel:
- name
- description;
Wrapper for SQL queries:
Create a wrapper module (package) for SQL queries in python that:
- Creates user, role and database.
- Assigns all privileges on the database to the role/user;
CLI:
Create cli for create / drop db with params such as: user, role, db;
Generate test data:
- 10 groups with randomly generated names. The name should contain 2 characters, hyphen, 2 numbers
(example: AA-11);
- Create 10 courses (math, biology, etc);
- 200 students. Take 20 first names and 20 last names and randomly combine them to generate students;
- Randomly assign students to groups. Each group could contain from 10 to 30 students; It is possible that some groups will be without students or students without groups;
Database:
Create relation MANY-TO-MANY between tables STUDENTS and COURSES. Randomly assign from 1 to 3 courses for each student;
- Write SQL queries using
sqlalchemy
orflask-sqlalchemy
:- Find all groups with less or equals student count;
- Find all students related to the course with a given course_id;
- Add a student to the course (from a list);
- Remove the student from one of his or her courses;
- CRUD operation for student / student list;
- CRUD operation for group;
- CRUD operation for course.
Other:
- Modify application using
Flask Rest Framework
; - Write tests using
Unittest
module orpytest
.
Installation:
First you need to create .env
file with environment variables at the root of the project, that contains:
POSTGRES_DB=superuser_database_name (by default: postgres)
POSTGRES_USER=superuser_login (by default: postgres)
POSTGRES_PASSWORD=superuser_password (by default: postgres)
PG_HOST=host_url (by default: localhost)
PG_PORT=postgres_port (by default: 5432)
PG_DB=your_database_name (by default: university)
PG_ROLE=your_role_name (example: admins)
PG_USER=your_user_name (example: admin)
PG_USER_PASSWORD=your_user_password
Or you can set these variables yourself.
Installation via Docker-compose:
STEP 1 - Install docker and docker compose:
For the beginning install docker
and docker compose
on your machine:
- docker
- docker-compose
- P.S.: Depending on the version use:
Or
docker compose
docker-compose
STEP 2 - Git clone:
- Then
git clone
this project in your folder. - And go to the folder where are
docker-compose.yml
andDockerfile
are located.
STEP 3 - Build project:
Use following command:
- default mode (production mode)
docker compose build
- or if you want to build development container:
docker compose -f docker-compose.dev.yml build
STEP 4 - Up the containers:
After image building, you can up the containers of one of these commands:
- default mode:
docker compose up
- background mode:
docker compose up -d
- or if you want to run in development mode:
docker compose -f docker-compose.dev.yml up
STEP 5 - Try to get data:
curl http://0.0.0.0:8080/api/v1/students/10
Or
curl http://0.0.0.0:8080/api/v1/students/10?full=true
Or
curl http://0.0.0.0:8080/api/v1/students?group=1&course=1
STEP 6 - Get api docs in your browser:
STEP 7 - Run pytest:
If you use development mode, you can run pytest:
- First, enter to the container:
docker exec -it university_api bash
- Second, run
pytest
command:cd tests/ && python -m pytest
STEP 8 - Stop and remove containers:
To remove
If you need:
- to stop the containers only:
docker compose stop
- to stop and remove the containers:
docker compose down
- if you have previously run a development container:
docker compose -f docker-compose.dev.yml stop
docker compose -f docker-compose.dev.yml down
STEP 9 - Remove all containers data:
- remove images:
docker rmi -f flask_rest_api_api
- remove volumes (database data):
docker volume rm -f flask_rest_api_psql_db
POSSIBLE ERRORS:
- if you get
postgres
warnings after app started, then you should probably change outer port forpostgres
indocker-compose.yml
:change to ↓ports: - '5432:5432'
ports: - '5632:5432'
- if you got something like this:
Use:
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:...
sudo chmod 666 /var/run/docker.sock
- if you use ubuntu, then you will probably have a problems with psycopg2.
So install this:
sudo apt-get install libpq-dev
Installation via IDE or other:
STEP 1 - Create env and install packages:
-
pip install pipenv
-
pipenv shell
-
Or
pipenv install
pipenv install --dev
STEP 2 - Start api:
Ubuntu
(Bash
):export PG_HOST=0.0.0.0 && cd api_university/ && export FLASK_APP=app.py && flask run
Windows
(PowerShell
):cd api_university/ $env:FLASK_APP = 'app.py' flask run
CMD
:cd api_university/ set FLASK_APP=app.py flask run
STEP 3 - Get api docs:
Get docs and data in your browser:
http://localhost/api/v1
Or
http://127.0.0.1:5000/api/v1
Or
http://0.0.0.0:5000/api/v1
Migrations:
If you begin only and have no database and have no migrations folder:
Get docs and data in your browser:
Ubuntu
(Bash
):cd api_university/ python3 -m scripts --create_db export FLASK_APP = 'app.py' flask db init flask db migrate flask db upgrade
Windows
(PowerShell
):cd api_university/ py -m scripts --create_db $env:FLASK_APP = 'app.py' flask db init flask db migrate flask db upgrade
If you want update models only:
Ubuntu
(Bash
):cd api_university/ export FLASK_APP = 'app.py' flask db migrate flask db upgrade
Windows
(PowerShell
):cd api_university/ $env:FLASK_APP = 'app.py' flask db migrate flask db upgrade
CLI
Simple command line interface, that:
- allows you to create db:
py -m api_university.scripts --create_db
- allows you to drop db:
py -m api_university.scripts --drop_db
- And contains optional arguments:
-
-d
,--db_name
, allows assign db name:py -m api_university.scripts --drop_db -d your_db_name
-
-u
,--user_name
, allows assign username:py -m api_university.scripts --create_db -u your_user_name
-
-r
,--role_name
, allows assign role name:py -m api_university.scripts --create_db -r your_role_name
-
-p
,--user_password
, allows assign user password:py -m api_university.scripts --create_db -p your_user_password
-
- Helper:
py -m api_university.scripts -h
IMPORTANT: If the arguments is not specified, it is taken from the env variables or set by default.