{"id":17793360,"url":"https://github.com/cevheri/pyfapi","last_synced_at":"2025-08-13T04:33:31.247Z","repository":{"id":258176815,"uuid":"872004559","full_name":"cevheri/pyfapi","owner":"cevheri","description":"Python FastAPI MongoDB CRUD Application end-to-end example","archived":false,"fork":false,"pushed_at":"2024-11-07T18:31:26.000Z","size":149,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-07T19:34:48.719Z","etag":null,"topics":["beanie","fastapi","jwt","oauth","openapi","pydantic","pytest","python","swagger","uvicorn"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cevheri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-13T14:41:42.000Z","updated_at":"2024-11-07T18:31:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"68e48d4d-618a-4c50-a05a-0d9aef6b45fa","html_url":"https://github.com/cevheri/pyfapi","commit_stats":null,"previous_names":["cevheri/pyfapi"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevheri%2Fpyfapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevheri%2Fpyfapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevheri%2Fpyfapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevheri%2Fpyfapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cevheri","download_url":"https://codeload.github.com/cevheri/pyfapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229737438,"owners_count":18116456,"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":["beanie","fastapi","jwt","oauth","openapi","pydantic","pytest","python","swagger","uvicorn"],"created_at":"2024-10-27T11:08:05.311Z","updated_at":"2024-12-14T17:45:12.509Z","avatar_url":"https://github.com/cevheri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyFApi\n\nPython FastAPI MongoDB CRUD Application end-to-end example\n\n## Overview\n\nThis project is a web application built with [FastAPI](https://fastapi.tiangolo.com/)\nand [MongoDB](https://www.mongodb.com/).\nIt provides a RESTful API for managing users and integrates Docker for containerization. The application is designed\nfollowing best practices for a clean architecture, making it easy to maintain and extend.\nIt is a simple CRUD application that allows to create, read, update, and delete.\n\nAlso, this project use pydantic, motor, beanie, and docker.\n\n---\n\n## Technologies\n\n- **[FastAPI](https://fastapi.tiangolo.com/)**: A modern, fast (high-performance) web framework for building APIs with\n  Python 3.6+ based on standard Python type hints.\n- **[MongoDB](https://www.mongodb.com/)**: A NoSQL database for storing user data.\n- **[Uvicorn](https://www.uvicorn.org/)**: Uvicorn is an ASGI web server implementation for Python.\n- **[Pydantic](https://pydantic-docs.helpmanual.io/)**: Pydantic is the most widely used data validation library for\n  Python.\n- **[Motor](https://motor.readthedocs.io/en/stable/)**: Motor presents a coroutine-based API for non-blocking access to\n  MongoDB from Tornado or asyncio.\n- **[Beanie](https://beanie-odm.dev/)**: Beanie - is an asynchronous Python object-document mapper (ODM) for MongoDB.\n  Data models are based on Pydantic.\n- **[Docker](https://www.docker.com/)**: Docker is a set of platform as a service products that use OS-level\n  virtualization to deliver software in packages called containers.\n- **[Oauth2](https://fastapi.tiangolo.com/tutorial/security)**: OAuth2 with Password (and hashing), Bearer with JWT\n  tokens.\n\n---\n\n## Setup and Installation\n\n### Prerequisites\n\n- Python 3.10+\n- Docker\n- Docker Compose\n- MongoDB\n- Git\n- FastAPI\n- Pydantic\n- Motor\n- Beanie\n- Uvicorn\n\n---\n\n### Before you begin\n\n- change the environment values with your own values in the .env.dev and .env.prod files\n- Find the change-me and replace it with your own values in source code\n\n---\n\n### Build and Run\n\n#### Uvicorn (development mode)\n\n- Clone the repository\n\n```bash\ngit clone https://github.com/cevheri/pyfapi.git\n```\n\n- Change the directory\n\n```bash\ncd pyfapi\n```\n\n- create a virtual environment\n\n```bash\npython3 -m venv venv\n```\n\n- Activate the virtual environment\n\n```bash\nsource venv/bin/activate\n```\n\n- Install the dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n- Create a .env file in the root directory and add the following environment variables\n\n```bash\ncp .env.default .env.dev\ncp .env.default .env.prod\n```\n\n- Run the application on local machine (development mode)\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --env-file .env.dev\n```\n\n- Run the application production mode with python\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --env-file .env.prod\n```\n\n#### python (development mode)\n\n```bash\npython3 main_dev.py\n```\n\n#### python (production mode)\n\n```bash\npython3 main_prod.py\n```\n\n#### Docker (development mode)\n\n* docker-compose.yaml file has three services: app, mongo, and mongo-express.\n\n```bash\ndocker-compose up --build\n```\n\n### Access the application\n\n- Open your browser and go to root url [http://localhost:8000](http://localhost:8000) to access the FastAPI application.\n- Open your browser and go to [http://localhost:8000/api/v1/docs](http://localhost:8000/api/v1/docs) to access the\n  Swagger UI.\n- Open your browser and go to [http://localhost:8081](http://localhost:8081) to access the MongoDB Express.\n\n---\n\n## Security\n\nSecurity is a critical aspect of any application. This project uses OAuth2 with Password (and hashing), Bearer with JWT\ntokens.\n\n* Security settings are defined in the [app/security](app/security) directory.\n* Security middleware is defined in the [app/middleware/security.py](app/middleware/security_middleware.py) file.\n\n### Allowed endpoints\n\n- if you want to allow the endpoint without authentication, you can add the endpoint to the env file like this:\n\n```bash\nSECURITY_ALLOWED_PATHS=/api/v1/public/products\n```\n\n---\n\n## Folder Structure\n\n| ...               | ...                           |\n|-------------------|-------------------------------|\n| -- app            | Main application directory    | \n| -- app/api        | API endpoints and routes      |\n| -- app/config     | Configuration settings        |\n| -- app/entity     | Database models               |\n| -- app/repository | Data access layer             |\n| -- app/service    | Business logic layer          |\n| -- app/schema     | API models                    |\n| -- app/security   | Security settings             |\n| -- app/utils      | Utility functions             |\n| -- app/main.py    | Main application file         |\n| -- tests          | Test cases                    |\n| -- .env.default   | Default environment variables |\n| ...               | ...                           |\n\n---\n\n## Adding new features\n\nThis project use a clean architecture, separation of concerns, and single responsibility principles.\nIf you want to add a new feature, you need to follow the structure of the project.\n\nFor example, you need product management features. You can follow the steps below.\n\n1. product_api.py: API endpoints and routes, request, and response models, and API logic. OpenAPI documentation, and\n   Swagger UI.\n2. product_service.py: Business logic layer\n3. product_dto.py: API models for API endpoints\n4. product_repository.py: Data access layer for database operations\n5. product.py: Database models for MongoDB (Beanie ODM)\n\n### Add new schema\n\n- Create a new file in the [app/schema](app/schema) like **product_dto.py** (use the existing files as a\n  reference [user_dto.py](app/schema/user_dto.py)) Classes: ProductDTO, ProductCreate, ProductUpdate\n\n### Add a new API endpoint / Route\n\n- Create a new file in the app/api directory like **product_api.py** (use the existing files as a\n  reference [user_api.py](app/api/user_api.py))\n- Edit the [app/api/__init__.py](app/api/__init__.py) file and add the new route\n\n### Add new service\n\n- Create a new file in the [app/service](app/service) like **product_service.py** (use the existing files as a\n  reference [user_service.py](app/service/user_service.py)) Classes: ProductService\n\n### Add new db-entity\n\nThis project use Beanie ODM for MongoDB. You can create a new entity for the database.\n\n- Create a new file in the [app/entity](app/entity) like **product.py** (use the existing files as a\n  reference [user.py](app/entity/user_entity.py)) Classes: Product\n- Edit the [app/entity/__init__.py](app/entity/__init__.py) file and add the new entity\n- Edit the [app/conf/env/db_config.py](app/conf/env/db_config.py) file and add the new entity **init_beanie()**\n-\n\n### Add new repository\n\n- Create a new file in the [app/repository](app/repository) like **product_repository.py** (use the existing files as a\n  reference [user_repository.py](app/repository/user_repository.py)) Classes: ProductRepository\n\n---\n\n## Run tests\n\nUnit tests and integration tests are essential for ensuring the quality of the application. This project uses pytest for\ntesting.\n\n- Folder structure\n\n| ...              | ...                            |\n|------------------|--------------------------------|\n| test             | Test cases                     |\n| tests/api        | API endpoints and routes tests |\n| tests/service    | Business logic layer tests     | \n| tests/repository | Data access layer tests        |\n\n- Run all tests\n\n```bash\nPYTHONPATH=. pytest\n```\n\nSample result :\n\n```bash\n22 passed in 0.52s\n```\n\n---\n\n## Conclusion\n\nThis FastAPI MongoDB application is structured to provide a robust and scalable API solution. By leveraging Docker and\nCI/CD practices, the application can be easily deployed and maintained.\n\nFeel free to contribute to this project by submitting issues or pull requests!\n\n---\n\n## References\n\n- [FastAPI](https://fastapi.tiangolo.com/)\n- [FastAPI \u0026 MongoDB - the full guide](https://github.com/fastapi/fastapi/discussions/9074)\n- [Build a Cocktail API with Beanie and MongoDB](https://www.mongodb.com/developer/languages/python/beanie-odm-fastapi-cocktails//)\n- [Pydantic](https://docs.pydantic.dev/dev/)\n- [Motor](https://motor.readthedocs.io/en/stable/tutorial-asyncio.html)\n- [Beanie Tutorial](https://beanie-odm.dev/getting-started/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcevheri%2Fpyfapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcevheri%2Fpyfapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcevheri%2Fpyfapi/lists"}