{"id":22351750,"url":"https://github.com/khaledsalshibani/inventory-management-api","last_synced_at":"2026-01-26T20:08:58.738Z","repository":{"id":263483305,"uuid":"885304088","full_name":"khaledsAlshibani/inventory-management-api","owner":"khaledsAlshibani","description":"a basic implementation showcasing the key aspects of building a RESTful API.","archived":false,"fork":false,"pushed_at":"2024-11-23T12:54:43.000Z","size":828,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-14T21:32:59.666Z","etag":null,"topics":["api","java","jwt","jwt-auth","mariadb","rest-api","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","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/khaledsAlshibani.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-08T10:28:10.000Z","updated_at":"2025-05-27T05:59:45.000Z","dependencies_parsed_at":"2025-10-14T21:31:31.323Z","dependency_job_id":"8218dd3b-4997-45c2-a2ac-dcf12ac34fec","html_url":"https://github.com/khaledsAlshibani/inventory-management-api","commit_stats":null,"previous_names":["khaledsalshibani/inventory-management-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/khaledsAlshibani/inventory-management-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaledsAlshibani%2Finventory-management-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaledsAlshibani%2Finventory-management-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaledsAlshibani%2Finventory-management-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaledsAlshibani%2Finventory-management-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khaledsAlshibani","download_url":"https://codeload.github.com/khaledsAlshibani/inventory-management-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaledsAlshibani%2Finventory-management-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28787030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","java","jwt","jwt-auth","mariadb","rest-api","spring-boot"],"created_at":"2024-12-04T12:15:04.291Z","updated_at":"2026-01-26T20:08:58.728Z","avatar_url":"https://github.com/khaledsAlshibani.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003eInventory Management API Documentation (Summarized)\u003c/h1\u003e\n\nThis document provides an introduction, explains the technologies used, API architecture, and includes an example endpoint explanation for learning purposes.\n\n---\n\n## Introduction\n\nThe **Inventory Management API** is a basic implementation showcasing the key aspects of building a RESTful API. It provides features for managing users, inventories, and products. The purpose of this API is to demonstrate backend concepts like layered architecture, authentication, and CRUD operations.\n\n---\n\n- [Introduction](#introduction)\n- [Technologies Used](#technologies-used)\n- [API Architecture](#api-architecture)\n  - [HTTP Methods:](#http-methods)\n  - [Path:](#path)\n  - [Headers:](#headers)\n  - [Authentication \\\u0026 Authorization:](#authentication--authorization)\n  - [Authorization Example in Postman:](#authorization-example-in-postman)\n  - [Login Example in Postman:](#login-example-in-postman)\n- [Endpoints](#endpoints)\n  - [Key Endpoints:](#key-endpoints)\n- [Directory Structure](#directory-structure)\n  - [Layers:](#layers)\n  - [Project Structure:](#project-structure)\n  - [Resources:](#resources)\n- [Example Endpoint: `GET /api/v1/inventories`](#example-endpoint-get-apiv1inventories)\n  - [Purpose](#purpose)\n  - [Request](#request)\n  - [Response](#response)\n    - [**Success Response** (200 OK):](#success-response-200-ok)\n    - [**Error Response** (401 Unauthorized):](#error-response-401-unauthorized)\n- [Usage](#usage)\n\n---\n\n## Technologies Used\n\n- **Java (Spring Boot)**: Framework used for API development.\n- **MariaDB**: Relational database for data storage.\n- **JWT (JSON Web Tokens)**: Token-based authentication mechanism.\n- **Apache Commons IO**: For file handling and I/O operations.\n- **Apache Tika Core**: For detecting and analyzing file types.\n- **IntelliJ IDEA**: Development environment.\n- **Maven**: Dependency management and project building.\n- **Postman**: API testing tool.\n\n---\n\n## API Architecture\n\nThe API is based on a simple, layered architecture for better maintainability and scalability.\n\n### HTTP Methods:\n- **GET**: Retrieve data (e.g., fetching inventories).\n- **POST**: Add new resources (e.g., creating a user).\n- **PUT**: Update existing resources (e.g., modifying inventory details).\n- **DELETE**: Remove resources (e.g., deleting products).\n\n### Path:\nAPI paths follow a hierarchical structure, starting with `/api/v1/` to indicate the version. The API runs on port `8082`.\n\nExamples:\n- `http://localhost:8082/api/v1/users`: GET/POST users.\n- `http://localhost:8082/api/v1/inventories`: GET/POST inventories.\n- `http://localhost:8082/api/v1/products`: GET/POST products.\n\n### Headers:\nEvery request to secured endpoints requires an `Authorization` header:\n```\nAuthorization: Bearer \u003cJWT_TOKEN\u003e\n```\n\n### Authentication \u0026 Authorization:\n\nThe API uses **JWT (JSON Web Tokens)** for secure communication, with **HS256** (HMAC with SHA-256) as the signing algorithm to ensure token integrity and security. Tokens are issued upon successful login and must be sent with subsequent requests in the `Authorization` header. Below is a visualization of the authorization process:\n\n![Authorization Process](assets/authorization.jpg)\n\n### Authorization Example in Postman:\n\nTo use the API in Postman, include the JWT token in the `Authorization` tab as a **Bearer Token**. Here's an example visualization:\n\n![Postman Authorization Example](assets/postman-authorization.png)\n\n### Login Example in Postman:\n\n![Login Example](assets/postman-login-example.png)\n\n---\n\n## Endpoints\n\n### Key Endpoints:\n1. **User Management**:\n   - `POST /api/v1/users`: Create a new user.\n   - `GET /api/v1/users/{id}`: Get details of a specific user.\n\n2. **Inventory Management**:\n   - `GET /api/v1/inventories`: List all inventories.\n   - `POST /api/v1/inventories`: Add a new inventory.\n\n3. **Product Management**:\n   - `GET /api/v1/products`: List all products.\n   - `POST /api/v1/products`: Add a new product.\n\n---\n\n## Directory Structure\n\nThe project follows an **N-Tier Architecture**, ensuring separation of concerns and modularity. Each layer is responsible for a specific functionality in the system. Below is a visualization of the architecture:\n\n![N-Tier Architecture](assets/layers.jpg)\n\n### Layers:\n\n1. **Controller Layer**: Handles API requests and responses. This layer interacts directly with the client.\n2. **Service Layer**: Contains business logic and ensures proper data processing between the controller and repository layers.\n3. **Repository Layer**: Handles database operations, such as querying and persisting data.\n\n### Project Structure:\n\n```\nsrc/main/java\n├── config       // Configuration classes (e.g., security, CORS)\n├── controller   // API endpoint handlers\n├── dto          // Data Transfer Objects for requests/responses\n├── entity       // Database entity classes\n├── exception    // Custom exception handling\n├── repository   // Interfaces for database operations\n├── service      // Business logic implementation\n├── util         // Utility classes (e.g., JWTUtil)\n```\n\n### Resources:\n\n- **`application.yml`**: Configuration file for the application (e.g., database connection, port settings).\n- **`static/images/user-photos`**: Static directory for storing user profile photos or other static assets.\n\n---\n\n## Example Endpoint: `GET /api/v1/inventories`\n\n![Example Endpoint Process](assets/endpoint-example.jpg)\n\n### Purpose\nRetrieve the list of all inventories.\n\n---\n\n### Request\n\n**HTTP Method**: `GET`  \n**Path**: `/api/v1/inventories`  \n**Headers**:\n```\nAuthorization: Bearer \u003cJWT_TOKEN\u003e\nContent-Type: application/json\n```\n\n---\n\n### Response\n\n#### **Success Response** (200 OK):\n```json\n[\n    {\n        \"id\": 17,\n        \"name\": \"Warehouse A\",\n        \"description\": \"Some text\",\n        \"status\": \"ACTIVE\",\n        \"inventoryType\": \"WAREHOUSE\",\n        \"address\": \"Jamal Abdulnasir\",\n        \"area\": 490.00,\n        \"availableArea\": 461.00,\n        \"createdAt\": \"2024-11-18T03:06:36.000+00:00\",\n        \"updatedAt\": \"2024-11-19T04:37:13.000+00:00\",\n    },\n    {\n        \"id\": 20,\n        \"name\": \"Store A\",\n        \"description\": \"I am Store \",\n        \"status\": \"ACTIVE\",\n        \"inventoryType\": \"WAREHOUSE\",\n        \"address\": \"Gamal Street, Taizz\",\n        \"area\": 500000.00,\n        \"availableArea\": 500000.00,\n        \"createdAt\": \"2024-11-18T19:47:31.000+00:00\",\n        \"updatedAt\": \"2024-11-18T19:47:31.000+00:00\",\n    }\n]\n```\n\n![Postman Success Response](assets/postman-success-get-inventories.png)\n\n---\n\n#### **Error Response** (401 Unauthorized):\n```json\n{\n  \"status\": \"error\",\n  \"error\": \"Invalid or expired token. Please log in again.\"\n}\n```\n\n![Postman Unauthorized Response](assets/unauthorized-request.png)\n\n--- \n\nThese responses demonstrate the behavior of the API when the request is successfully authenticated or when the request fails due to missing or invalid authentication.\n\n---\n\n## Usage\n\n1. **Import the Database**  \n   The database structure and initial data can be found in the following file:  \n   [inventory_management.sql](assets/db).  \n   - Use your preferred database tool (e.g., MySQL Workbench, phpMyAdmin, or command line) to import the SQL file into your MySQL server.\n\n   **Default User Credentials**:  \n   - **Username**: `n`  \n   - **Password**: `n`\n\n2. **Start MySQL**  \n   Ensure your MySQL server is running and accessible. Update the `application.yml` file in the project with the correct database credentials and connection URL if required.\n\n3. **Run the API**  \n   Start the API using Maven or your preferred IDE (e.g., IntelliJ IDEA):  \n   The API will start on the base URL `http://localhost:8082/`.\n\n4. **Test the API**  \n   Use tools like **Postman** to interact with the API. Ensure you include the JWT token in the `Authorization` header for secured endpoints.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhaledsalshibani%2Finventory-management-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhaledsalshibani%2Finventory-management-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhaledsalshibani%2Finventory-management-api/lists"}