{"id":22332521,"url":"https://github.com/theoddysey/atlas","last_synced_at":"2026-04-17T05:02:19.895Z","repository":{"id":256417049,"uuid":"763525360","full_name":"TheODDYSEY/Atlas","owner":"TheODDYSEY","description":"ECommerce REST API 🤖 with Flask  PostgreSQL 🛢️  SQLAlchemy and Docker 🐳","archived":false,"fork":false,"pushed_at":"2024-09-10T13:19:06.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T15:24:46.972Z","etag":null,"topics":["api","authentication","flask","gunicorn","postman","postresql","python"],"latest_commit_sha":null,"homepage":"https://www.postman.com/theoddysey/rest-api-flask-python/collection/4c5nmyt/rest-api-flask-python","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/TheODDYSEY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2024-02-26T13:12:06.000Z","updated_at":"2024-10-30T19:20:00.000Z","dependencies_parsed_at":"2024-09-10T16:25:46.904Z","dependency_job_id":"64c9da29-6ccb-4933-a5a3-8eae70d342e0","html_url":"https://github.com/TheODDYSEY/Atlas","commit_stats":null,"previous_names":["theoddysey/atlas"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheODDYSEY/Atlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheODDYSEY%2FAtlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheODDYSEY%2FAtlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheODDYSEY%2FAtlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheODDYSEY%2FAtlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheODDYSEY","download_url":"https://codeload.github.com/TheODDYSEY/Atlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheODDYSEY%2FAtlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31915900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"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":["api","authentication","flask","gunicorn","postman","postresql","python"],"created_at":"2024-12-04T04:18:30.177Z","updated_at":"2026-04-17T05:02:19.870Z","avatar_url":"https://github.com/TheODDYSEY.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ECommerce REST API with Flask ,PostgreSQL ,SQLAlchemy  and Docker\n![Flask](https://img.shields.io/badge/flask-%23000.svg?style=for-the-badge\u0026logo=flask\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Postgres](https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white)\n![Gunicorn](https://img.shields.io/badge/gunicorn-%298729.svg?style=for-the-badge\u0026logo=gunicorn\u0026logoColor=white)\n![Postman](https://img.shields.io/badge/Postman-FF6C37?style=for-the-badge\u0026logo=postman\u0026logoColor=white)\n![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)\n\n[![Interact with API](https://img.shields.io/badge/Interact_with_API-FF6C37?style=for-the-badge\u0026logo=postman\u0026logoColor=white)](https://www.postman.com/theoddysey/rest-api-flask-python/collection/4c5nmyt/rest-api-flask-python)\n\n\nA robust RESTful API developed using Flask, providing comprehensive CRUD functionalities for managing stores, items, and tags, complete with secure user authentication, authorization, and detailed role-based access control. This project serves as an excellent foundation for scalable e-commerce or inventory management systems, leveraging Python's simplicity and the power of RESTful architecture.\n![REST API Architecture](./rest-api.png)\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Core Features](#core-features)\n3. [System Requirements](#system-requirements)\n4. [Installation](#installation)\n   - [Local Setup](#local-setup)\n   - [Docker Setup](#docker-setup)\n5. [Architecture](#architecture)\n6. [API Documentation](#api-documentation)\n    - [Items Endpoints](#items-endpoints)\n    - [Stores Endpoints](#stores-endpoints)\n    - [Tags Endpoints](#tags-endpoints)\n    - [User Endpoints](#user-endpoints)\n7. [Authentication and Authorization](#authentication-and-authorization)\n8. [Error Handling and Validation](#error-handling-and-validation)\n9. [Postman Collection](#postman-collection)\n10. [Testing](#testing)\n11. [Contribution Guidelines](#contribution-guidelines)\n12. [License](#license)\n\n## Overview\n\nThis project is a production-ready REST API built using Flask, a micro-framework in Python. The API provides a fully-functional backend service for managing stores, items, and tags, complete with comprehensive authentication and authorization layers. It supports user roles and permissions using JWT (JSON Web Tokens), ensuring secure data access.\n\nDesigned to be scalable and easily extendable, this API is perfect for both small-scale applications and large-scale microservices architectures.\n\n## Core Features\n\n- **RESTful API Design**: Clean and consistent REST API design patterns are followed, adhering to REST principles.\n- **CRUD Operations**: Robust support for Create, Read, Update, and Delete operations on stores, items, and tags.\n- **Authentication and Authorization**: Secure user authentication with JWTs, providing access control for protected routes.\n- **Tag Management System**: Advanced tagging capabilities for categorizing and linking items in stores.\n- **Error Handling**: Comprehensive error handling with custom error messages and HTTP status codes.\n- **Data Validation**: Input validation using `marshmallow` schema for all endpoints to ensure data integrity.\n- **Extensible Architecture**: Modular code structure with clear separation of concerns, making it easy to extend.\n- **Database Integration**: Uses SQLAlchemy for ORM, with SQLite as the default database (easily configurable for other DBs).\n- **Containerized Deployment**: Docker support for easy deployment and scaling in different environments.\n\n## System Requirements\n\n- **Python**: 3.7 or higher\n- **Flask**: 2.0 or higher\n- **pip**: Package manager for Python\n- **Docker**: 20.10 or higher (if using Docker)\n- **Postman**: For API testing and development\n\n## Installation\n\n### Local Setup\n\n#### 1. Clone the Repository\n\nClone the repository to your local machine using the following command:\n\n```bash\ngit clone https://github.com/TheODDYSEY/Rest-api-flask-python.git\ncd Rest-api-flask-python\n```\n\n#### 2. Create and Activate a Virtual Environment\n\nIt's best practice to use a virtual environment to manage dependencies:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows use `venv\\Scripts\\activate`\n```\n\n#### 3. Install the Required Dependencies\n\nInstall all required dependencies using the provided `requirements.txt` file:\n\n```bash\npip install -r requirements.txt\n```\n\n#### 4. Run Database Migrations\n\nEnsure that the database is set up properly:\n\n```bash\npython manage.py db init\npython manage.py db migrate\npython manage.py db upgrade\n```\n\n#### 5. Start the Flask Application\n\nStart the application on your local development server:\n\n```bash\npython run.py\n```\n\nThe API is now accessible at `http://127.0.0.1:5000`.\n\n### Docker Setup\n\nThe project includes a `Dockerfile` for containerized deployment. Docker allows you to run the application in an isolated environment, ensuring consistency across different development and production setups.\n\n#### 1. Build the Docker Image\n\nNavigate to the project root directory and build the Docker image:\n\n```bash\ndocker build -t flask-rest-api .\n```\n\n#### 2. Run the Docker Container\n\nRun the Docker container from the built image:\n\n```bash\ndocker run -p 80:80 flask-rest-api\n```\n\nThe API will be accessible at `http://localhost:80`.\n\n#### Dockerfile Explanation\n\nThe provided `Dockerfile` is optimized for a lightweight production environment:\n\n```Dockerfile\nFROM python:3.10\nWORKDIR /app\nCOPY ./requirements.txt requirements.txt\nRUN pip install --no-cache-dir --upgrade -r requirements.txt\nCOPY . .\nCMD [\"gunicorn\", \"--bind\", \"0.0.0.0:80\", \"app:create_app()\"]\n```\n\n- **Base Image**: Uses the official Python 3.10 image.\n- **Working Directory**: Sets `/app` as the working directory.\n- **Dependency Installation**: Installs all dependencies from `requirements.txt`.\n- **Copy Application Code**: Copies the application code into the container.\n- **Run Command**: Uses Gunicorn as the WSGI HTTP server to run the Flask application, binding it to port `80`.\n\n## Architecture\n\nThe project follows a modular architecture with the following key components:\n\n- **App Module**: Contains the main Flask application factory, including all configurations and extensions.\n- **Models Module**: Contains all SQLAlchemy models representing `Stores`, `Items`, `Tags`, and `Users`.\n- **Resources Module**: Contains the RESTful resources for handling HTTP requests and responses.\n- **Schemas Module**: Contains Marshmallow schemas for serializing and deserializing JSON data.\n- **Services Module**: Handles core business logic and data manipulation.\n- **Security Module**: Handles JWT token creation, validation, and user authentication.\n\n## API Documentation\n\nThe API supports CRUD operations across several entities. Below are detailed descriptions of the endpoints:\n\n### Items Endpoints\n\n- **GET /item**: Retrieve a list of all items.\n  - **Request**: `GET /item`\n  - **Response**: Returns a JSON array of all items.\n\n- **POST /item**: Create a new item.\n  - **Request**: `POST /item`\n  - **Headers**: `Authorization: Bearer \u003ctoken\u003e`\n  - **Body**:\n    ```json\n    {\n      \"name\": \"Table\",\n      \"price\": 17.99,\n      \"store_id\": 1\n    }\n    ```\n  - **Response**: Returns the created item details.\n\n- **PUT /item/{id}**: Update an existing item by its ID.\n  - **Request**: `PUT /item/1`\n  - **Headers**: `Authorization: Bearer \u003ctoken\u003e`\n  - **Body**:\n    ```json\n    {\n      \"name\": \"Another Chair\",\n      \"price\": 20.50,\n      \"store_id\": null\n    }\n    ```\n  - **Response**: Returns the updated item details.\n\n- **DELETE /item/{id}**: Delete an item by its ID.\n  - **Request**: `DELETE /item/1`\n  - **Headers**: `Authorization: Bearer \u003ctoken\u003e`\n  - **Response**: Returns a success message.\n\n### Stores Endpoints\n\n- **GET /store**: Retrieve a list of all stores.\n  - **Request**: `GET /store`\n  - **Response**: Returns a JSON array of all stores.\n  \n- **POST /store**: Create a new store.\n  - **Request**: `POST /store`\n  - **Body**:\n    ```json\n    {\n      \"name\": \"My Store 3\"\n    }\n    ```\n  - **Response**: Returns the created store details.\n\n- **DELETE /store/{id}**: Delete a store by its ID.\n  - **Request**: `DELETE /store/1`\n  - **Headers**: `Authorization: Bearer \u003ctoken\u003e`\n  - **Response**: Returns a success message.\n\n### Tags Endpoints\n\n- **POST /store/{id}/tag**: Create a new tag for a store.\n  - **Request**: `POST /store/1/tag`\n  - **Body**:\n    ```json\n    {\n      \"name\": \"Tag name\"\n    }\n    ```\n  - **Response**: Returns the created tag details.\n\n- **GET /tag/{id}**: Retrieve information about a tag by its ID.\n  - **Request**: `GET /tag/1`\n  - **Response**: Returns the details of the tag.\n\n### User Endpoints\n\n- **POST /register**: Register a new user.\n  - **Request**: `POST /register`\n  - **Body**:\n    ```json\n    {\n      \"username\": \"newUser\",\n      \"password\": \"password123\"\n    }\n    ```\n  - **Response**: Returns a success message with user details.\n\n- **POST /login**: Authenticate a user and generate a JWT.\n  - **Request**: `POST /login`\n  - **Body**:\n    ```json\n    {\n      \"username\": \"newUser\",\n      \"password\": \"password123\"\n    }\n    ```\n  - **Response**: Returns a JWT for subsequent requests.\n\n## Authentication and Authorization\n\nThe API uses JWT (JSON Web Tokens) for authentication and authorization. JWTs are generated during user login and must be included in the `Authorization` header for protected endpoints.\n\n## Error Handling and Validation\n\nThe API follows robust error handling mechanisms using Flask's error handler methods. Input validation is handled using `marshmallow` schemas to ensure data integrity and proper response formatting.\n\n## Postman Collection\n\nTo facilitate easy testing and development, a Postman collection is included in the repository. It contains all API endpoints, sample requests, and responses.\n\n- [Access the Postman File ](https://www.postman.com/theoddysey/rest-api-flask-python/collection/4c5nmyt/rest-api-flask-python)\n\n## Testing\n\nUnit tests are written using Python's built-in `unittest` module. To run the tests:\n\n```bash\npython -m unittest discover -s tests\n```\n\n## Contribution Guidelines\n\nContributions are welcome! Please fork the repository and submit a pull request for review.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoddysey%2Fatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheoddysey%2Fatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoddysey%2Fatlas/lists"}