Merge pull request #81 from ProgrammingBuddies/readme

Readme

Author: petak5

README.md

@@ -2,10 +2,16 @@
 
 API backend for [Programming Buddies](https://github.com/ProgrammingBuddies/programmingbuddies-ui) (projects management)
 
+## API documentation
+The documentation is dynamically generated by the server using [Swagger](https://swagger.io) and [Swagger UI](https://swagger.io/tools/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](#environment)
 - Install [docker-compose](https://docs.docker.com/compose/install/) and do `docker-compose up`
+- for information on how to authenticate for the API, see [authentication](#authentication)
 
 ## Set up guide: The 'bothersome' way
 
@@ -25,6 +31,7 @@ Requirements:
 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](#authentication)
 
 ## Environment
 
@@ -36,19 +43,37 @@ Run the server:
     - 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](https://github.com/ProgrammingBuddies/programmingbuddies-api/blob/develop/example.env)
 
-### Testing
+## 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`
+- 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`
 
-## Milestones
-- [ ] build DB and endpoints with basic CRUD
-- [ ] add security for app (ie - bots, and non-human actors/clients)
-- [ ] add users and profile stores as well as registration/management API endpoints for users
 ## Tech stack:
 
 - Python

example.env

@@ -1,6 +1,6 @@
 CONNECT=mysql+mysqlconnector://user:password@localhost:3306/meintest
 FLASK_ENV=development
-APP_SECRET=guest
+APP_SECRET=ThisShouldBeSomeSuperHardToGuessPassphrase-ByNotChangingThisDefaultValueYouPutYourServicesIntoRisk
 GITHUB_ID=c1fed8b3f0e10e0beef
 GITHUB_SECRET=de79b512d6fbeefa9cdc113beef219ccc7cd98f1
-JWT_SECRET_KEY=guest
+JWT_SECRET_KEY=ThisTooShouldBeSomeSuperHardToGuessPassphrase-ByNotChangingThisDefaultValueYouPutYourServicesIntoRisk