Restfulness

Your team's social bookmarking app

This project is going to be an opensource version of something like Delicious to save and share your favorite bookmarks.

Now you can save your favourite bookmarks, categories them, return them by category or by looking for some special keyword in their URL, see your friends activities (If they are public), ...

And last but not least, you can setup Restfulness on your own workspace, because both server and clients are opensource and ready for use.

Production Environment (Using Docker)

If you have docker and docker-compose installed, then simply you can run:

(Make sure you are in root directory of project which is the folder that contains api.py)

docker-compose up

And that's it :) now you can open http://localhost:5000/apidocs to see available APIs.

(To run CI tests using pytest in this way, you can simply run docker-compose run app python -m pytest; But make sure to wait a few seconds for MySql to get ready)

By default, our docker-compose configuration will disables root's password for MySql after initialization; So app connects to restfulness database with test user which is created using enviromental variables in docker-compose.yml file. If you want to changes this setting, make sure to read MySql Docker Documentation, then change docker-compose.yml and config.json correctly.

Note: By default, Database is persistent using Docker Volumes, so you don't need to worry about losing your data unless you turn off everything using docker-compose down -v command. To make a long story short and for more information, take a look at this.

Development Environment (Without Docker)

At the very beginning, you have to initiate a virtual environment with this:

sudo apt install -y python3-venv
python3 -m venv venv

And then every time that you want to run it:

source venv/bin/activate
python -m pip install -r requirements.txt

Then you can run

python api.py

Database Connection

This project supports both MySql and SQLite as its database.

By default, this code uses MySql as its main database but if you want to use SQLite (which is placed in tests/test.db) for testing purposes, make sure to change mysql option to false in config.json.

Else, if you want to continue using MySql, please follow instructions below:

Before running api.py, make sure you have mysql server installed and change db connection in config.json.

To install mysql server in Debian based distributions you can run:

sudo apt install mysql-server
sudo mysql_secure_installation

Now change username, password and db in config.json to make the app able to connect to database.

Config.json

Before running the app, make sure to check all values in config.json file.

• Default values:

  • reset password token expire time = 300 seconds
  • verify random code token expire time = 300 seconds
  • reset password code length = 8
  • serializer secret key = "VERY_SECRET" #Should be changed!!!
  • socializing date format = %Y-%m-%d %H:%M #YYYY-MM-DD hh:mm

• SMTP:

  If you want to be able to enable sending Email part, you have to configure SMTP part in config file. (If you don't have any service, you can use Google's Free SMTP Server, but if you are using this, please make sure to Enable less secure apps to access Gmail).

• Pagination:

  • maximum links per page = 10
  • maximum activities per page = 12

Tests

Something that is untested is broken! To run tests, make sure you are in root directory of the project (the directory that contains api.py file) then run:

python -m pytest

API Documentation

To see available APIs, go to http://localhost:5000/apidocs (We are using Flasgger for our API's documentation)

Clients

• Restfulness Flutter App

Notes

• How does reset password mechanism work?
  1. Client sends a POST request to /forget endpoint, containing user's username.
  2. Server sends an 8 digit random created code to user's Email and returns a hash string which contains User's ID, Valid 8 digit code and expire date. (We use ItsDangerous for creating that hash, so it's safe.)
  3. Client sends a POST request to /verify endpoint, containing user's entered 8 digit code and hash that was obtained from previous call.
  4. Server returns a token for resetting password, If user entered the correct 8 digit code.
  5. At last, Client sends a POST request to /reset endpoint, containing Reset password token that is obtained from previous call and user's new password.
  6. For more information, read this. (To make long story short, we do this to pick up unnecessary pressure from our server.)

License

MIT

For more information read this:

• https://flask-restful.readthedocs.io/en/latest/quickstart.html#a-minimal-api
• https://flask-jwt-extended.readthedocs.io/en/stable/basic_usage
• https://python-jsonschema.readthedocs.io/en/stable/
• https://flask.palletsprojects.com/en/1.1.x/testing/
• http://sqlalchemy.org/