{"id":29628887,"url":"https://github.com/devilkiller-ag/quillist-api","last_synced_at":"2025-07-21T09:07:06.982Z","repository":{"id":289763570,"uuid":"970579691","full_name":"devilkiller-ag/quillist-api","owner":"devilkiller-ag","description":"Quillist API - Book Review API","archived":false,"fork":false,"pushed_at":"2025-05-03T07:41:56.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-03T08:43:24.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devilkiller-ag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-22T08:16:14.000Z","updated_at":"2025-05-03T07:41:59.000Z","dependencies_parsed_at":"2025-04-24T23:32:10.668Z","dependency_job_id":"0e8aa6eb-2df2-4532-8b2a-07fbe7b5998b","html_url":"https://github.com/devilkiller-ag/quillist-api","commit_stats":null,"previous_names":["devilkiller-ag/quillist-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devilkiller-ag/quillist-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devilkiller-ag%2Fquillist-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devilkiller-ag%2Fquillist-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devilkiller-ag%2Fquillist-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devilkiller-ag%2Fquillist-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devilkiller-ag","download_url":"https://codeload.github.com/devilkiller-ag/quillist-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devilkiller-ag%2Fquillist-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266270599,"owners_count":23902738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-21T09:07:05.297Z","updated_at":"2025-07-21T09:07:06.976Z","avatar_url":"https://github.com/devilkiller-ag.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quillist API - Book Review API\n\nQuillist API is a RESTful API built with FastAPI for managing book reviews. It provides endpoints for user authentication, book management, and review submission. The API is designed to be efficient, scalable, and easy to use. It leverages modern Python features and libraries to provide a robust backend solution for book review applications.\n\n- Quillist API is live at [https://quillist-api.onrender.com/auth/v1](https://quillist-api.onrender.com/auth/v1)\n- Quillist API Swagger UI documentation is live at [https://quillist-api.onrender.com/auth/v1/docs](https://quillist-api.onrender.com/auth/v1/docs)\n- Quillist API ReDoc documentation is live at [https://quillist-api.onrender.com/auth/v1/redoc](https://quillist-api.onrender.com/auth/v1/redoc)\n- Quillist API OpenAPI specification is live at [https://quillist-api.onrender.com/auth/v1/openapi.json](https://quillist-api.onrender.com/auth/v1/openapi.json)\n\n**NOTE:** User Signup, password reset, email verification and other email related features are not available in the live version of the API as it requires **paid background worker service hosting**. You can test these features locally by running the API on your machine.\n\nFor testing purposes, you can use the following credentials:\n\n```\n\"user\": {\n        \"uid\": \"4e66ac0d-0e61-408d-974d-9e8d6a5b6ba6\",\n        \"username\": \"quillist\",\n        \"email\": \"testuser@quillist.com\",\n        \"first_name\": \"Quillist\",\n        \"last_name\": \"Ray\",\n        \"is_verified\": true,\n        \"created_at\": \"2025-05-04T03:21:40.610001\",\n        \"updated_at\": \"2025-05-04T03:21:40.610011\"\n    }\n```\n\n## Features \u0026 Progress\n\n### Core API Functionality\n\n- [x] Project setup with FastAPI CLI\n- [x] Basic web server implementation\n- [x] API versioning\n- [x] API routing with FastAPI routers\n\n### Database Integration\n\n- [x] Database setup with SQLModel and PostgreSQL\n- [x] Asynchronous database connections\n- [x] Database migrations using Alembic\n- [x] Environment configuration with Pydantic settings\n- [x] Lifespan events for database connection management\n\n### CRUD Operations for Books\n\n- [x] Book model creation\n- [x] CURD operations for books\n\n### Authentication \u0026 Authorization\n\n- [x] User model creation\n- [x] User registration endpoint\n- [x] Password hashing with Passlib\n- [x] JWT authentication with PyJWT\n- [x] User login endpoint\n- [x] HTTP Bearer authentication\n- [x] Refresh token implementation\n- [x] Token revocation using Redis\n- [x] Role-based access control\n- [x] Current user retrieval endpoint\n- [x] Role checker dependency\n\n### Model \u0026 Schema Relationships\n\n- [x] User-book relationship modeling\n- [x] User-review relationship modeling\n- [x] Nested schema serialization\n\n### Middleware \u0026 Error Handling\n\n- [x] Custom exception classes\n- [x] Exception handlers registration\n- [x] Custom logging middleware\n- [x] CORS middleware integration\n- [x] Trusted hosts configuration\n\n### Email Support\n\n- [x] FastAPI-Mail setup\n- [x] Email sending functionality\n- [x] User account verification via email\n- [x] Password reset emails\n\n### Background Tasks\n\n- [x] FastAPI background tasks\n- [x] Celery integration with Redis\n- [x] Celery worker setup\n- [x] Flower monitoring for Celery\n\n### Testing \u0026 Documentation\n\n- [x] API documentation with SwaggerUI and ReDoc\n- [x] Unit testing with Unittest Mock and Pytest\n- [x] Document-driven testing with Schemathesis\n\n### Deployment\n\n- [x] Deployment on Render.com\n\n## Role Based Access Control\n\nThe API supports role-based access control (RBAC) to manage user permissions. The following roles are defined:\n\n- `admin`: Full access to all endpoints.\n- `user`: Limited access to user-specific endpoints.\n\nThe `admin` role can perform these actions:\n\n- Add users\n- Change user roles\n- CURD on users\n- CURD on books\n- CURD on reviews\n- Revoking access tokens\n\nThe `user` role can perform these actions:\n\n- CURD on their own book submissions\n- CURD on their own reviews\n- CURD on their own account\n\n## Project Setup\n\nTo set up the project, follow these steps:\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/devilkiller-ag/quillist-api.git\n   ```\n\n2. **Navigate into the project directory:**\n\n   ```bash\n   cd quillist-api\n   ```\n\n3. **Create a virtual environment:**\n\n   - On macOS/Linux:\n     ```bash\n     python3 -m venv venv\n     ```\n   - On Windows:\n     ```bash\n     python -m venv venv\n     ```\n\n4. **Activate the virtual environment:**\n\n   - On macOS/Linux:\n     ```bash\n     source venv/bin/activate\n     ```\n   - On Windows:\n     ```bash\n     venv\\Scripts\\activate\n     ```\n\n5. **Install the required dependencies:**\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n6. **Define enviornment variables**\n   Create a `.env` file in the root folder and define all required enviornment variables.\n\n```\nAPI_URL=\n\nDATABASE_URL=\nREDIS_URL=\n\nJWT_SECRET=\nJWT_ALGORITHM=\n\nMAIL_USERNAME=\nMAIL_PASSWORD=\nMAIL_SERVER=\nMAIL_PORT=\nMAIL_FROM=\nMAIL_FROM_NAME=\n```\n\n7. **Run the application:**\n   ```bash\n   fastapi dev src/\n   ```\n\nThe application should now be up and running within the virtual environment.\n\n- You can access the API at `http://localhost:8000`.\n- You can access the API documentation in **Swagger UI** at `http://localhost:8000/docs`.\n- You can access the API documentation in **ReDoc** at `http://localhost:8000/redoc`.\n- You can access the API documentation in **OpenAPI specification** at `http://localhost:8000/openapi.json`.\n\n8. **Run Celery worker for background tasks:**\n   Open a new terminal window, activate the virtual environment, and run the following command to start the Celery worker:\n\n   ```bash\n   celery  -A src.celery_tasks.celery_app worker\n   ```\n\n9. **Run Flower for monitoring Celery tasks (Optional):**\n   Open another terminal window, activate the virtual environment, and run the following command to start Flower:\n\n   ```bash\n   celery -A src.celery_tasks.celery_app flower\n   ```\n\n   Flower will be accessible at `http://localhost:5555`.\n\n10. **Run Alembic migrations:**\n    To apply database migrations, run the following command:\n\n    ```bash\n    alembic upgrade head\n    ```\n\n    This will apply all pending migrations to the database.\n\n11. **Run tests:**\n    To run the tests, use the following command:\n\n    ```bash\n    pytest\n    ```\n\n    This will execute all the tests in the `tests` directory.\n    You can also run a specific test file or test case by specifying the path:\n\n    ```bash\n      pytest tests/test_file.py\n    ```\n\n    or\n\n    ```bash\n       pytest tests/test_file.py::test_case_name\n    ```\n\n    This will run only the specified test case.\n\n12. **Generate and run tests with Schemathesis (Document Driven Testing):**\n\n    - To generate tests using Schemathesis, use the following command:\n\n    ```bash\n    st run http://127.0.0.1:8000/api/v1/openapi.json --experimental=openapi-3.1\n    ```\n\n    This will generate and run tests based on the OpenAPI specification.\n\n    - You can also specify a specific endpoint to test:\n\n    ```bash\n    st run http://127.0.0.1:8000/api/v1/openapi.json --experimental=openapi-3.1 --endpoint /api/v1/books\n    ```\n\n    This will generate and run tests only for the specified endpoint.\n\n## Technologies Used\n\n- **FastAPI** for building the API.\n- **PostgreSQL** (NeonDB) for database.\n- **SQLAlchemy** and **SQLModel** for database ORM.\n- **Alembic** for database migrations.\n- **Pydantic** for data validation.\n- **UUID** for generating unique identifiers.\n- **JWT** for authentication.\n- **Passlib** for password hashing.\n- **itsdangerous** for generating and verifying tokens.\n- **FastAPI-Mail** for sending emails.\n- **Logging** for logging.\n- **Redis** for Token blacklisting, and Background Task queue (ex: sending emails).\n- **Celery** for background tasks (ex: sending emails).\n- **Flower** for background task monitoring.\n- **Asgiref** for async function to sync function conversion.\n- **Pytest** for testing.\n- **Schemathesis** for document driven testing.\n- **OpenAPI Specification**, **Swagger UI** and **Redoc** for API documentation.\n- **Python-dotenv** for environment variable management.\n- **Render** for deploying the API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevilkiller-ag%2Fquillist-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevilkiller-ag%2Fquillist-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevilkiller-ag%2Fquillist-api/lists"}