Board Game REST API built using Flask allowing users browse board games, add them to a personal collection and share reviews with other users.

The API is currently deployed through Heroku and can be accessed here. Find authentication information and API documentation below.

The project was created as the final project for the API Development and Documentation module of Udacity's Full Stack Developer Nanodegree.

• Flask is a lightweight backend microservices framework. Flask is required to handle requests and responses for our REST API.

• SQLAlchemy and Flask-SQLAlchemy are the ORM (Object-relatonal mapping) libraries of choice, used to define our domain models and handle all database interactions.

• Alembic and Flask-Migrate is a lightweight database migration tool used to manage changes to the domain models and update the database accordingly.

• authlib and Auth0 to manage user authentication and authorization using JWT RBAC (Role-based access control).

• jose JavaScript Object Signing and Encryption for JWTs. Used for encoding, decoding, and verifying JWTs, specifically to extract RBAC information for our application.

• Swagger to document the API endpoints.

1. Create a new virtual environment: python3 -m venv venv and activate: source venv/bin/activate
2. Install all dependencies: pip install -r requirements.txt

With Postgres running, create the required databases for each configuration:

createdb boardgames
createdb boardgames_dev
createdb boardgames_test

These databases are initially seeded with dummy data when starting the Flask server.

python runserver.py

Running the above will start the server on localhost:5000/api.

Pytest was used as the testing framework for this project.

To deploy the tests, simply run:

python -m pytest

Example output:

platform linux -- Python 3.8.10, pytest-7.1.2, pluggy-1.0.0
rootdir: /home/matt/dev/boardgame-tracker
plugins: mock-3.8.2
collected 52 items

tests/auth/test_auth0.py ......
tests/auth/test_rbac.py .
tests/integration/test_board_games.py ........
tests/integration/test_collections.py .....
tests/integration/test_reviews.py ..........
tests/integration/test_search.py .
tests/integration/test_users.py ..
tests/unit/test_board_game.py ....
tests/unit/test_collection.py .....
tests/unit/test_review.py .........
tests/unit/test_user.py .

============ 52 passed ============

A Postman collection is also included in this repo which can be imported and run to test the authorization and authentication functionality of the API.

Auth0 is a flexible, drop-in solution to add authentication and authorization services to applications. It minimises the cost, time, and risk associated with building an in-house solution to authenticate and authorize users.

The Auth0 JWT includes claims for permissions based on the user's role within the Auth0 system. Endpoints with the requires_auth decorator will check if a particular permission exists within the JWT permissions claim of the currently logged in user.

The following is optional! Users can link this API to their own Auth0 account using the following steps:

1. Create a new Auth0 Account
2. Select a unique tenant domain
3. Create a new, single page web application
4. Register a new API
   • in API Settings:
     • Enable RBAC
     • Enable Add Permissions in the Access Token
5. Create new API permissions:
   • patch:designer
   • post:designers
   • post:reviews
   • patch:reviews
   • delete:review
   • post:games
   • patch:games
   • delete:games
   • post:publishers
   • patch:publisher
   • patch:reactions
   • post:genres
   • patch:genres
   • patch:collection
6. Create new roles for:
   • User
     • can delete:review
     • can patch:reactions
     • can patch:reviews
     • can post:reviews
   • Admin
     • can perform all actions
7. Create two new accounts and assign the accounts a role from above.

Update the following environmental variables in .env by retrieving this values from your new Auth0 application:

• AUTH0_CLIENT_ID
• AUTH0_CLIENT_SECRET
• AUTH0_DOMAIN
• API_AUDIENCE

You will now be able to login to the API using the newly created users through your Auth0 account.

The API is currently hosted on Heroku and can be accessed here: https://board--game--tracker.herokuapp.com/api

As discussed above, many of the API endpoints must be authorized by checking for a particular permission in the claims of the user's JWT. Two dummy user accounts have been set up to allow users to generate JWTs with different permissions associated with them:

Admin
email: admin@games.io
password: Jdvru3$29W6A6aM

User
email: user@games.io
password: C8Jf&PPbUW&g$At

1. Go to https://board--game--tracker.herokuapp.com/auth/login
2. This will redirect you to the Auth0 login page.
3. Enter the credentials above.
4. Once logged in, you will be redirected to https://board--game--tracker.herokuapp.com/auth which will display the current JWT being used.
5. This JWT can then be used in further tests through Postman.

Alternatively, users are welcome to set up their own accounts.

Full API documentation can be found at https://board--game--tracker.herokuapp.com/swagger.

Below is a brief outline of some of the key endpoints:

GET /auth

• Display current user ID and JWT

GET /auth/login

• Redirect users to Auth0 login page

GET /auth/logout

• Clear current user from the session and logout

Base url: /api

GET, POST /games

• Get all games (paginated) and add new games

GET, PATCH, DELETE /games/{id}

• Get a game by id, update a game and delete a game

GET /games/{id}/reviews

• Get all reviews for a game

GET, POST /designers

• Get all designer details and create new designers GET, PATCH /api/designers/{id}
• Get a designer by id and update a designer

GET, POST /genres

• Get all genre details and create new genres GET, PATCH /genres/{id}
• Get a genre by id and update a genre

GET, POST /publishers

• Get all publisher details and create new publishers GET, PATCH /publishers/{id}
• Get a publisher by id and update a publisher

POST /search

• Search for a board game where the title matches a search term

GET, POST /reviews

• Get all reviews (paginated) and submit new reviews

GET, PATCH, DELETE reviews/{id}

• Get a review by id, update a review and delete a review

GET, PATCH /reviews/{id}/reactions

• Get all reactions for a review and like/dislike a review

GET /users/{id}/reviews

• Get all reviews submitted by a user

GET, PATCH /collections/{id}/games

• Get all games in a collection; add/remove games from a collection

PATCH /collections/{id}/privacy

• Toggle the privacy of a collection

Further ideas for continued development of this project:

• Board game recommendation algorithm based on user's current collection and reviews.
• Allow users to log board game sessions and tag other users.
• Build out front end application.