{"id":26754943,"url":"https://github.com/pcisha/animal-kingdom","last_synced_at":"2025-06-19T11:35:41.375Z","repository":{"id":274050332,"uuid":"921748163","full_name":"pcisha/animal-kingdom","owner":"pcisha","description":"Animal Kingdom [APIs]","archived":false,"fork":false,"pushed_at":"2025-01-24T14:56:56.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T14:17:15.671Z","etag":null,"topics":["api-rest","microservice"],"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/pcisha.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}},"created_at":"2025-01-24T14:41:04.000Z","updated_at":"2025-01-24T14:56:59.000Z","dependencies_parsed_at":"2025-01-24T15:44:24.974Z","dependency_job_id":null,"html_url":"https://github.com/pcisha/animal-kingdom","commit_stats":null,"previous_names":["pcisha/animal-kingdom"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pcisha/animal-kingdom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcisha%2Fanimal-kingdom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcisha%2Fanimal-kingdom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcisha%2Fanimal-kingdom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcisha%2Fanimal-kingdom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pcisha","download_url":"https://codeload.github.com/pcisha/animal-kingdom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pcisha%2Fanimal-kingdom/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260743123,"owners_count":23055896,"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":["api-rest","microservice"],"created_at":"2025-03-28T14:17:19.434Z","updated_at":"2025-06-19T11:35:36.353Z","avatar_url":"https://github.com/pcisha.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Animal Kingdom Application\n\nA Spring Boot application that provides APIs to manage a hierarchical tree structure of animals, enabling users to retrieve and manipulate the tree.\n\n\n### Features\n\n- **Get the Entire Animal Tree**  \n  - Retrieve the complete tree structure of animals, including all nested children.\n  - Supports hierarchical JSON output.\n\n- **Add a New Animal**  \n  - Add a new animal under a specified parent (by ID).\n  - Ensures unique IDs and validates inputs.\n\n\n### Technology Stack\n\n- Java 17.\n- Spring Boot 3.4.1.\n- Gradle 8.12 for build and dependency management.\n- JUnit 5 for testing.\n- Mockito for mocking.\n\n\n### API Endpoints\n\n#### 1. Get the Entire Tree\n- **Endpoint**: `GET /api/tree`\n- **Description**: Returns the entire tree of animals, including all children.\n- **Request Body**: None\n- **Response Body**: Tree-structure with Animals (parent, label, children and ID).\n- **Response Codes**: `200 OK`: Tree retrieved successfully. `404 NOT FOUND`: Tree is empty.\n\n#### 2. Add a New Animal\n- **Endpoint**: `POST /api/tree`\n- **Description**: Adds a new animal under the specified parent (by ID).\n- **Request Body (example)**: \n`{\n  \"parent\": \"1\",\n  \"label\": \"tiger\"\n}`\n- **Response Body (example)**: `{\n  \"animalId\": \"3\",\n  \"label\": \"tiger\",\n  \"parent\": \"1\"\n}`\n- **Response Codes**: `201 CREATED`:  Animal added successfully. `400 BAD REQUEST`: Invalid input or parent not found.\n\n\n### Setup\n\n- Gradle build in the project root folder: `gradle clean build`\n- Run the `AnimalKingdomApplication.java`\n- Access the base URL: `http://localhost:8888`\n- Access the Actuator Health URL: `GET http://localhost:8888/actuator/health`\n- Get the entire Animal tree: `GET localhost:8888/api/tree`\n- Add a new Animal: `POST localhost:8888/api/tree`\n\n\n### Project Structure\n\n- `controller/` for API endpoints and DTOs.\n- `service/` for business logic.\n- `model/` for domain model (Animal).\n- `utilities/` for utilities, processing and data manipulation.\n- `application.properties` for application configuration.\n- `test/` for controller integration and service layers unit tests.\n\n\n### Design Choices\n\n- **Best Practices**:\n  - Built using **Spring Boot**, **Java**, and **Gradle**, adhering to **MVC (Model-View-Controller)** architecture and industry best practices.\n\n- **Model and DTOs**:\n  - Introduced a dedicated `Animal` model class to represent each node in the tree.\n  - Custom API DTO objects are used to decouple internal models from API payloads, enhancing maintainability.\n\n- **Utility Classes**:\n  - Utility classes were implemented to abstract:\n    - Configuration logic.\n    - Data processing and manipulation.\n    - Error handling and logging support.\n\n- **In-Memory Data Loader**:\n  - A data loader initializes an in-memory tree data set to simulate persistence of `Animal` objects.\n\n- **Logging**:\n  - Structured logging added at both controller and service layers for better traceability.\n\n- **Health Monitoring**:\n  - Actuator's health endpoint (`/actuator/health`) is included to provide application status monitoring.\n\n- **Configuration**:\n  - Custom application configuration properties defined in `application.properties`.\n  - Gradle configurations optimized for project dependencies and build management.\n\n- **Testing**:\n  - Comprehensive tests implemented:\n    - **Controller integration tests** for API endpoints.\n    - **Service layer unit tests** for business logic.\n\n- **Tree Representation**:\n  - The tree is represented as a `List\u003cMap\u003cString, Animal\u003e\u003e`.\n  - Each `Map` contains:\n    - A unique ID as the key.\n    - An `Animal` object as the value.\n\n- **ID Generation**:\n  - A utility method performs a **Depth-First Search (DFS)** to find the maximum numeric ID.\n  - Generates a new unique ID for any newly added `Animal` object.\n\n- **Edge Cases**:\n  - Proper handling for:\n    - Adding an animal with a non-existent parent.\n    - Adding an animal with a blank or malformed label.\n    - Processing empty or malformed request bodies.\n\n- **.gitignore**:\n  - A `.gitignore` file is included to ensure unnecessary files (e.g., `build/` and IDE-specific files) are excluded from the repository.\n\n\n### Future Improvements\n\n- **Handle Additional Edge Cases**:\n    - Prevent duplicate IDs or labels under the same parent to maintain data consistency.\n    - Add safeguards for circular references in the tree structure.\n\n- **Database Persistence**:\n    - Replace the in-memory data store with a relational database such as H2 (for development) or PostgreSQL (for production).\n    - Implement an efficient schema to support tree structures using parent-child relationships.\n\n- **Swagger Integration**:\n    - Use springdoc-openapi to automatically generate API documentation.\n    - Provide a user-friendly UI for testing and exploring endpoints.\n\n- **Concurrency Handling**:\n    - Introduce thread safety to the tree operations to ensure consistent behavior during concurrent API requests.\n    - Use synchronized blocks or thread-safe collections for shared resources.\n\n- **Testing Enhancements**:\n    - Expand test coverage to include End-to-end integration tests for the complete API.\n    - Additional, edge cases like malformed input or large datasets.\n    - Concurrency testing to verify thread safety.\n\n- **Custom Error Handling and Validation**:\n    - Improve error handling by introducing custom exception classes for different error scenarios.\n    - A centralized exception handler using @ControllerAdvice.\n    - Validate API requests with stricter rules (e.g., @NotBlank, @Size, and regex patterns).\n\n- **Performance Optimization**:\n    - Implement lazy loading to fetch only the required portion of the tree, reducing unnecessary data transfer.\n    - Use caching tools like Spring Cache or Redis for frequently accessed data (e.g., root nodes or commonly requested subtrees).\n\n- **Enhanced Security**:\n    - Authentication mechanisms like Token-based authentication using JWT.\n    - OAuth2 for secure user authorization.\n    - Apply CORS policies to restrict API access to trusted origins.\n    - Encrypt sensitive data and enforce HTTPS for communication.\n\n- **Support for Bulk Operations**:\n    - Add a dedicated bulk API (POST /api/tree/bulk) to allow the addition or update of multiple nodes in a single request.\n\n- **Deployment and Scalability**:\n    - Add containerization with Docker for consistent and portable deployments.\n    - Set up CI/CD pipelines using tools like Jenkins, GitHub Actions, or GitLab CI for automated builds, testing, and deployment.\n\n- **Monitoring and Observability**:\n    - Integrate tools like Prometheus and Grafana for monitoring API performance and resource usage.\n    - Add custom application metrics using Actuator and Micrometer.\n\n#\nDate: January 24, 2025\n\nAuthor: Prachi Shah @ https://pcisha.my.canva.site/\n\nP.S. The default copyright laws apply.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpcisha%2Fanimal-kingdom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpcisha%2Fanimal-kingdom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpcisha%2Fanimal-kingdom/lists"}