{"id":31322779,"url":"https://github.com/oleksandr-romashko/goit-pythonweb-hw-08","last_synced_at":"2026-05-01T21:04:52.245Z","repository":{"id":315243330,"uuid":"1053569072","full_name":"oleksandr-romashko/goit-pythonweb-hw-08","owner":"oleksandr-romashko","description":"REST API to store and manage your contacts, built using FastAPI","archived":false,"fork":false,"pushed_at":"2025-09-17T15:15:29.000Z","size":951,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T19:28:42.650Z","etag":null,"topics":["alembic","api","asyncio","crud","dotenv","fastapi","postgres","pydantic","python","rest","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oleksandr-romashko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T16:16:56.000Z","updated_at":"2025-09-22T10:22:47.000Z","dependencies_parsed_at":"2025-09-17T14:36:59.897Z","dependency_job_id":"09683f45-06e7-4829-aae9-9079407cf62c","html_url":"https://github.com/oleksandr-romashko/goit-pythonweb-hw-08","commit_stats":null,"previous_names":["oleksandr-romashko/goit-pythonweb-hw-08"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/oleksandr-romashko/goit-pythonweb-hw-08","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleksandr-romashko%2Fgoit-pythonweb-hw-08","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleksandr-romashko%2Fgoit-pythonweb-hw-08/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleksandr-romashko%2Fgoit-pythonweb-hw-08/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleksandr-romashko%2Fgoit-pythonweb-hw-08/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oleksandr-romashko","download_url":"https://codeload.github.com/oleksandr-romashko/goit-pythonweb-hw-08/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleksandr-romashko%2Fgoit-pythonweb-hw-08/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32512684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["alembic","api","asyncio","crud","dotenv","fastapi","postgres","pydantic","python","rest","sqlalchemy"],"created_at":"2025-09-25T19:13:59.305Z","updated_at":"2026-05-01T21:04:52.232Z","avatar_url":"https://github.com/oleksandr-romashko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fullstack Web Development with Python \u003c!-- omit in toc --\u003e\n\n### [# goit-pythonweb-hw-08](https://github.com/topics/goit-pythonweb-hw-08) \u003c!-- omit in toc --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg align=\"center\" src=\"./asserts/thumbnail.svg\" width=\"200\" title=\"Project thumbnail\" alt=\"project thumbnail\"\u003e\n\u003c/p\u003e\n\n## Building a REST API for Contact Management using FastAPI. \u003c!-- omit in toc --\u003e\n\nThis project demonstrates the use of **FastAPI** to build a REST API for managing personal contacts, along with **SQLAlchemy ORM** for relational **PostgreSQL** database operations, and **Alembic** for schema migrations.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./asserts/project-showcase.jpg\" alt=\"Project showcase image\" width=\"600\"\u003e\n\u003c/p\u003e\n\nThe app allows storing and managing contacts with fields like `first_name`, `last_name`, `email`, `phone_number`, `birthdate`, and optional additional info.\n\nMain features:\n* Full CRUD operations for managing contacts.\n* Search functionality by first name, last name, or email.\n* Retrieve contacts with upcoming birthdays (next 7 days).\n* SQLAlchemy ORM modeling and Alembic migrations.\n* Swagger/OpenAPI documentation automatically generated by FastAPI.\n* Pydantic models for request validation and data serialization.\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n- [Task Requirements](#task-requirements)\n  - [Goal](#goal)\n  - [Technical Specification](#technical-specification)\n    - [1. Contacts](#1-contacts)\n    - [2. API](#2-api)\n    - [3. CRUD + Extra Features](#3-crud--extra-features)\n  - [General Requirements](#general-requirements)\n- [Task Solution](#task-solution)\n  - [Solution Description](#solution-description)\n  - [Project Setup \\\u0026 Run Instructions](#project-setup--run-instructions)\n    - [Prerequisites](#prerequisites)\n    - [Setting Up the Development Environment](#setting-up-the-development-environment)\n      - [1. Clone the Repository and Install Dependencies](#1-clone-the-repository-and-install-dependencies)\n      - [2. Setup database](#2-setup-database)\n      - [3. Setup application connection to the database](#3-setup-application-connection-to-the-database)\n      - [4. Migrate and synchronize database ORM with database schema](#4-migrate-and-synchronize-database-orm-with-database-schema)\n      - [5. Start FastAPI application](#5-start-fastapi-application)\n      - [6. Access API docs and make API requests](#6-access-api-docs-and-make-api-requests)\n- [License](#license)\n\n## Task Requirements\n\n### Goal\n\nCreate a REST API for storing and managing personal contacts.\nThe API must be built with FastAPI and use SQLAlchemy to work with a database.\n\n### Technical Specification\n\n#### 1. Contacts\n\nDesign a database to store contact information.\n\nEach contact record must include:\n* First name\n* Last name\n* Email address\n* Phone number\n* Birthday\n* Additional information (optional)\n\n#### 2. API\n\nDevelop an API, that should support basic data operations.\n\nIt must support following functions and provide endpoints to:\n* Create a new contact\n* Retrieve a list of all contacts\n* Retrieve a single contact by its ID\n* Update an existing contact\n* Delete a contact\n\n#### 3. CRUD + Extra Features\n\nIn addition to standard CRUD operations, the API must also:\n* Allow searching contacts by first name, last name, or email using query parameters.\n* Provide an endpoint to retrieve contacts who have birthdays within the next 7 days.\n\n### General Requirements\n\n1. Use FastAPI to implement the REST API.\n2. Use SQLAlchemy ORM for database operations.\n3. Use PostgreSQL as the database.\n4. Support CRUD operations for contacts.\n5. Store each contact's birthday.\n6. Expose Swagger documentation for the REST API.\n7. Validate request data with Pydantic models.\n\n## Task Solution\n\n### Solution Description\n\nThe solution consists of a **PostgreSQL database** running in a Docker container, a **FastAPI server** for handling HTTP API requests and managing contacts in the database, and **Swagger/OpenAPI documentation** that describes all available endpoints and allows you to try out requests directly from the documentation.\n\n### Project Setup \u0026 Run Instructions\n\nThis guide will help you set up the environment and run the project.\n\n#### Prerequisites\n\nBefore you begin, make sure you have the following installed:\n\n* **[Python 3.11.*](https://www.python.org/downloads/)** (tested with Python 3.11.13) — Required to run the application locally.\n* **[Poetry](https://python-poetry.org/)** - To manage dependencies in virtual environment.\n* **[Docker](https://www.docker.com/)** using PostgreSQL (tested with PostgreSQL 17.5) — Used to containerize the application in a unified environment using Docker or Docker Compose.\n* Optional - for local development:\n  * **[Git](https://git-scm.com/downloads)** — To clone the repository, version control and development.\n  * **[VS Code](https://code.visualstudio.com/download)** or another IDE — Recommended for browsing and editing the project source code, run using run scripts and overall development.\n  * **DBeaver** or **PgAdmin** to access and see you PostgreSQL database information\n\n#### Setting Up the Development Environment\n\n##### 1. Clone the Repository and Install Dependencies\n\n1. Clone repository:\n    ```bash\n    git clone https://github.com/oleksandr-romashko/goit-pythonweb-hw-08\n    cd goit-pythonweb-hw-08\n    ```\n    or download the ZIP archive from [GitHub Repository](https://github.com/oleksandr-romashko/goit-pythonweb-hw-08) and extract it.\n2. Install project dependencies:\n    ```bash\n    poetry install\n    ```\n\n##### 2. Setup database\n\nDada are stored in Postgres database. To easily setup our own one for testing purposes we may use Docker.\n\nTo create Postgres database in Docker container use following command:\n\n```shell\ndocker run --name contacts-manager \\\n  -p 5432:5432 \\\n  -e POSTGRES_USER=app_user \\\n  -e POSTGRES_PASSWORD=your_db_password_here \\\n  -e POSTGRES_DB=contacts_app \\\n  -d postgres\n```\n\nwhere:\n- `contacts-manager` - name of Docker container (you may set your own container name)\n- `app_user` - Postgres username, setup with admin privileges by Docker\n- `your_db_password_here` - password for the user (create your own one)\n- `contacts_app` - database name to connect to\n- `5432:5432` - exposed external/internal container ports to access postgres database from the outside\n- `postgres` - Docker image name to base our container on (we use PostgreSQL, so `postgres` in our case)\n\n##### 3. Setup application connection to the database\n\nFor app to access data in database we need correctly setup connection configuration.\n\nThere is [.env.example](./.env.example) in project root folder. Copy it and rename to `.env`. This file serves as a application configuration template and contains database connection settings (values should correspond to those, set during docker database creation):\n```env\n# ==========================\n# Database Settings\n# ==========================\n\n# Hostname or IP of the PostgreSQL server\nDB_HOST=0.0.0.0\n\n# Port PostgreSQL listens on\nDB_PORT=5432\n\n# Name of the database your app will use\nDB_NAME=contacts_app\n\n# App-level PostgreSQL user and password\nDB_USER=app_user\nDB_PASSWORD=your_db_password_here\n```\n\nMake sure you `DB_PASSWORD` value correspond to `POSTGRES_PASSWORD` during Docker database creation.\n\nNow our app should be set up to connect to our database in Docker container.\n\n##### 4. Migrate and synchronize database ORM with database schema\n\nAs soon as we may connect to database we may perform queries. But our database has no tables or structure that conform to one set in ORM yet.\n\nTo comply our database with expected structure, execute following command:\n\n```bash\npoetry run alembic upgrade head\n```\n\nThis will add tables with columns to database, that respect latest ORM structure.\n\n```shell\n$ poetry run alembic upgrade head\nINFO  [alembic.runtime.migration] Context impl PostgresqlImpl.\nINFO  [alembic.runtime.migration] Will assume transactional DDL.\nINFO  [alembic.runtime.migration] Running upgrade  -\u003e 0378c40d374e, Init\n```\n\nOther useful Alembic commands:\n\n* `poetry run alembic downgrade base` - downgrade database to basic (initial at clone) state\n* `poetry run alembic revision --autogenerate -m \"revision message\"` - automatically create new migration script\n* `poetry run alembic history` - show migrations history\n* `poetry run alembic current` - show current revision hash (useful to locate position in entire history)\n* `poetry run alembic upgrade \u003crevision hash\u003e` - upgrade to certain revision\n* `poetry run alembic downgrade \u003crevision hash\u003e` - downgrade to certain revision\n* `poetry run alembic downgrade -1` - downgrade to the previous revision\n\n##### 5. Start FastAPI application\n\nBefore we may start our FastAPI application it is wise to check our application settings. Check your `.env` file and change FastApi application settings if necessary:\n\n```env\n# ==========================\n# FastAPI Application Settings\n# ==========================\n\n# Port on which the FastAPI app will run\nWEB_PORT=3000\n\n# Enable debug mode (also can trigger auto-reload in dev)\nDEBUG=False\n```\n\nThen start FastApi application by using following command:\n\n```shell\npoetry run python -m src.main\n```\n\nThis will start application and it will be accessible at [http://0.0.0.0:3000](http://0.0.0.0:3000) (depending on your `WEB_PORT` settings).\n\n##### 6. Access API docs and make API requests\n\nYou may access Swagger API documentation at [http://0.0.0.0:3000/docs](http://0.0.0.0:3000/docs) and make API requests from there.\n\n**Happy coding!**\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\nYou are free to use, modify, and distribute this software in accordance with the terms of the license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleksandr-romashko%2Fgoit-pythonweb-hw-08","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foleksandr-romashko%2Fgoit-pythonweb-hw-08","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleksandr-romashko%2Fgoit-pythonweb-hw-08/lists"}