Programming Buddies API

API backend for Programming Buddies (projects management)

API documentation

The documentation is dynamically generated by the server using Swagger and Swagger UI

• To view the documentation run the server using one of the set up guides below and then head to /docs endpoint
  • e.g. https://localhost:5001/docs for local development

Set up guide: The simple way

• Set up your environment
• Install docker-compose and do docker-compose up
• for information on how to authenticate for the API, see authentication

Set up guide: The 'bothersome' way

Requirements:

• Set up your environment
• MySQL Community Server
  • Add line CONNECT=mysql+pymysql://<user>:<password>@localhost:3306/<database name> to your .env file to specify connection parameters
• Pipenv
  1. Run python -m pip install pipenv to install pipenv
  2. Run pipenv install inside the repository
     • If you have multiple Python versions installed you might need to specify which one to use pipenv install --python=python3.7
• SSL
  • On Mac or Linux install the OpenSSL tool and run openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365 inside the repository
  • On Windows
    1. Install OpenSSL for Windows here
    2. Execute the same command as on Mac inside the project directory

Run the server:

• pipenv run python src/runserver.py
  • Run with flag --reset-db to drop and recreate all tables on start
• For information on how to authenticate for the API, see authentication

Environment

1. Create a file named .env
   • Add line FLASK_ENV=development to have the server automatically restart on file changes
2. Add line APP_SECRET=somepassword as app secret. This is used to sign sessions among other things and is required
3. Obtain credentials for GitHub OAuth
   • Under your GitHub account Settings go to Developer settings and OAuth Apps
   • Create a new one and set the homepage url to https://localhost:5001/ and Authorization callback to https://localhost:5001/login/github/authorized
   • Copy the Client Id and Client Secret from that site and save them in .env as GITHUB_ID and GITHUB_SECRET respectively
4. Furthermore a JWT_SECRET_KEY is required for signing the JWT-tokens
   • Pick a strong passphrase so that attackers can't brute-force it and sign tokens distinguishing as your server

Your .env file should now look something like example.env

Authentication

• To authenticate you have to specify several attributes
  • account - currently github is the only supported value
  • username - your username of account on specified platform in the previous point
  • redirect - url where should you be redirected after authenticating with OAuth
• Put it all these together https://<url:port>/<login-or-register>?account=<account>&username=<username>&redirect=<redirect>
  • e.g.: https://localhost:5001/<login-or-register>?account=github&username=freddy&redirect=https://localhost:5001 will login-or-register using GitHub account with name freddy while developing local with the server hosted on localhost:5001
• You will be redirected to the specified url and get data with it
  • If the request failed - when logging in and user was not registered (user not found in the database) or there was any internal error, you will get an error message and code
  • If the request succeeded - you will get a JWT token in the URL, that is what you need to authenticate
• Add to your requests Authorization header with a value Bearer <token> where you replace <token> with your token acquired in the step above

Login

• /login route logs in if the user exists in the database, otherwise returns a error message and code in the URL
• Usage: https://<url:port>/login?account=<account>&username=<username>&redirect=<redirect>
  • e.g.: https://localhost:5001/login?account=github&username=freddy&redirect=https://localhost:5001

Register

• /register route either logs in if the user exists in the database or registers (creates) a new user, in case of failure returns a error message and code in the URL
• Usage: https://<url:port>/register?account=<account>&username=<username>&redirect=<redirect>
  • e.g.: https://localhost:5001/register?account=github&username=freddy&redirect=https://localhost:5001

Testing

• To run multiple tests just specify the directory which contains them for example pipenv run pytest tests/
  • This will run all the tests in the tests directory
• If you want to run test cases only in a particular file, then just give the full file path pipenv run pytest tests/example.py

Tech stack:

• Python
• Flask
• MySQL
• pyOpenSSL