Java Bootcamp Project - RESTful API for Music Album Management
Loads on-demand to minimize costs. Takes ~5-7 minutes to load database and Java application.
Enter your email address to be notified when ready (optional).
The Music Library API is a comprehensive backend application developed as a final bootcamp project, demonstrating professional-grade software engineering practices. This RESTful API provides complete CRUD operations for managing a music catalog including artists, albums, and genres with sophisticated relationship management. Album track integration can be added as the next feature.
Built following best practices for layered architecture, this project showcases expertise in Spring Boot ecosystem, database design, API development, testing strategies, and cloud deployment practices. The application features a comprehensive music library with 50 artists and over 100 albums, now deployed on AWS cloud infrastructure with production-grade reliability.
Live AWS Production API: http://project.jcarl.net/api
Deployment Status: Validated with 121 requests, 484 tests, 100% pass rate
Full Create, Read, Update, Delete functionality adhering to REST principles with proper HTTP status codes and standardized response envelopes.
Managed One-to-Many (Artist-Album) and Many-to-Many (Album-Genre) JPA relationships with bidirectional synchronization and orphan removal.
Optimized data retrieval using Spring Data Pageable to handle large datasets efficiently without performance bottlenecks.
Advanced filtering system using JPA Specifications to query by title, release date ranges, and genre associations dynamically.
Strict data integrity enforcement using JSR-380 (Bean Validation) custom constraints at the API boundary to prevent malformed data.
Centralized @RestControllerAdvice mechanism that transforms Java exceptions into user-friendly, consistent JSON error responses.
Self-documenting API using Swagger UI (OpenAPI 3.0), allowing developers to visualize and test endpoints directly in the browser.
Comprehensive suite including Unit tests with Mockito, Integration tests using Testcontainers to real database interactions, and Maven Surefire test reporting.
Custom integration with the iTunes Search API to automatically discover, fetch, and resize high-resolution album artwork.
The application follows a layered architecture pattern with clear separation of concerns, promoting maintainability, testability, and scalability. Each layer has distinct responsibilities and communicates through well-defined interfaces.
Handles HTTP requests and responses, maps URLs to service methods, validates input, and formats output. Uses Spring MVC annotations for RESTful endpoint definition.
@RestControllerMain REST controller exposing all API endpoints for Artists, Albums, and Genres. Implements comprehensive
OpenAPI annotations for documentation. Handles pagination with @ParameterObject Pageable.
@ControllerRedirects root URL to Swagger UI for convenient API documentation access.
Contains business logic, transaction management, and orchestrates operations between controllers and repositories.
Annotated with @Service and @Transactional for proper transaction boundaries.
@Service @TransactionalManages artist CRUD operations with pagination support. Throws ResourceNotFoundException
for missing entities. Uses constructor injection via @RequiredArgsConstructor.
@Service @TransactionalHandles album operations including complex many-to-many genre relationships. Implements advanced search using JPA Specifications. Manages bidirectional relationship synchronization with explicit Hibernate initialization.
@Service @TransactionalManages genre entities and their album associations. Provides methods for adding/removing albums from genres while maintaining referential integrity.
Interfaces extending Spring Data JPA repositories for database operations. Provides automatic CRUD implementation and custom query methods using Spring Data naming conventions.
extends JpaRepository<Artist, Long>Data access interface for Artist entities. Inherits standard CRUD and pagination methods from JpaRepository.
extends JpaRepository, JpaSpecificationExecutorRepository with custom query methods: findByArtist_ArtistId() and findByGenres_GenreId().
Implements JpaSpecificationExecutor for dynamic query building.
extends JpaRepository<Genre, Long>Simple repository interface for Genre entity persistence operations.
JPA entities representing database tables with proper relationships, validation constraints, and lifecycle callbacks. Uses Lombok for boilerplate reduction and Jackson annotations for JSON serialization control.
@Entity @Table(name="artist")Fields: artistId (PK), name (required, max 255), description (TEXT), createdAt, updatedAt
Relationships: One-to-Many with Album (cascade ALL, orphan removal)
Features: @PrePersist/@PreUpdate for timestamps, @JsonIgnore on albums collection to prevent cycles
@Entity @Table(name="album")Fields: albumId (PK), title (required), releaseDate, coverImageUrl, trackCount, catalogNumber (unique),
createdAt, updatedAt
Relationships: Many-to-One with Artist (required), Many-to-Many with Genre via join table
Features: Transient getReleaseYear() method, custom setGenres() for bidirectional sync, LAZY fetching
@Entity @Table(name="genre")Fields: genreId (PK), name (required, max 100), description (TEXT), createdAt, updatedAt
Relationships: Many-to-Many with Album (inverse side, EAGER fetch for testing)
Features: @JsonIgnore on albums to break serialization cycles, @EqualsAndHashCode.Exclude on collections
Implements the Specification pattern for building dynamic, type-safe queries with JPA Criteria API.
Specification<Album>Provides static factory methods for album filtering:
• titleContains(String) - Case-insensitive title search
• releasedBetween(Integer, Integer) - Date range filtering
• hasGenre(Long) - Filter by genre association with JOIN
Centralized exception handling using Spring's @RestControllerAdvice for consistent error responses across the API.
@RestControllerAdviceHandles multiple exception types with specific handlers:
• MethodArgumentNotValidException → 400 (validation errors)
• ConstraintViolationException → 400 (constraint violations)
• ResourceNotFoundException → 404 (entity not found)
• MethodArgumentTypeMismatchException → 400 (type errors)
• HttpMessageNotReadableException → 400 (malformed JSON)
• Exception → 500 (unexpected errors with logging)
extends RuntimeExceptionCustom exception thrown when requested entities don't exist. Automatically converted to 404 responses by GlobalExceptionHandler.
@BuilderUniform error response DTO containing: timestamp, status code, error type, message, request path, and optional validation error list. Provides consistent error format across all endpoints.
All endpoints are prefixed with /api and return JSON responses.
/api/artists - Create a new artist
/api/artists?page=0&size=20&sort=name,asc - Get paginated artists
/api/artists/{id} - Get artist by ID
/api/artists/{id} - Update artist
/api/artists/{id} - Delete artist
/api/artists/{artistId}/albums - Get all albums by artist
/api/albums - Create a new album
/api/albums?page=0&size=20 - Get paginated albums
/api/albums/{id} - Get album by ID
/api/albums/{id} - Update album
/api/albums/{id} - Delete album
/api/genres - Create a new genre
/api/genres?page=0&size=20 - Get paginated genres
/api/genres/{id} - Get genre by ID
/api/genres/{id} - Update genre
/api/genres/{id} - Delete genre
/api/genres/{genreId}/albums - Get all albums by genre
Comprehensive input validation using Bean Validation (JSR-380) annotations:
Properly managed JPA relationships with:
Flexible data retrieval with:
Multi-layered testing approach:
Professional database practices:
Comprehensive OpenAPI 3.0 documentation:
The Music Library API is deployed on Amazon Web Services (AWS) using modern cloud-native technologies and best practices for production-grade applications. The deployment leverages containerization and serverless compute for scalability, reliability, and cost-effectiveness.
Domain: project.jcarl.net
Port: 80 (HTTP)
DNS Provider: Namesilo with automated API-based updates
Container Platform: AWS ECS Fargate (Serverless)
Task Revision: Latest (auto-deployed via ECS)
Build Environment: AWS CloudShell + CodeBuild
The AWS deployment has been thoroughly validated using Postman collection runner with comprehensive test coverage:
33+ Docker builds executed through AWS CloudShell and CodeBuild, demonstrating iterative development and continuous improvement of the containerized application.
11+ ECS task definition updates deployed, reflecting ongoing optimization of container configurations, resource allocation, and environment variables.
Custom DNS update script integrated with Namesilo API to automatically update A records when ECS assigns new public IPs, ensuring zero-downtime availability.
Features: Simple deployment, automatic HTTPS, built-in database
Use Case: Evaluated as an alternative cloud deployment option
Note: AWS ECS Fargate was selected for production deployment
Features: Secure tunneling, temporary public URLs, webhook testing
Use Case: Previously used for local development, testing, and demonstration purposes
Note: This was a temporary development configuration and is no longer active
This project evolved through several deployment iterations, overcoming real-world cloud infrastructure challenges and implementing production-grade solutions. Each challenge provided valuable learning experiences in DevOps and cloud architecture.
Diagnosed and resolved DNS resolution failures caused by duplicate A records pointing to old and new IPs. Implemented proper DNS record cleanup logic in the automation script, ensuring single authoritative A record per deployment and preventing DNS propagation conflicts.
Resolved automatic task rollbacks triggered by ECS Circuit Breaker due to health check failures. Debugged container startup issues, corrected environment variable configurations, and validated health check endpoints to achieve stable deployments without rollbacks.
Overcame local Docker Desktop limitations on Windows LTSB by pivoting to AWS CloudShell as the primary build environment. Leveraged CloudShell's pre-configured Docker and AWS CLI to establish a reliable, cloud-based build pipeline independent of local system constraints.
Navigated AWS IAM role and policy configurations to establish secure, least-privilege access patterns. Configured ECS task execution roles, ECR permissions, RDS security groups, and VPC networking to ensure secure communication between services while maintaining production security standards.
Migrated from AWS Route 53 to Namesilo DNS API for automated domain management. Implemented custom DNS update automation to dynamically update A records when ECS tasks receive new public IPs, ensuring continuous availability at project.jcarl.net without manual intervention.
Leveraged AWS CloudShell as a cloud-based Docker build environment, eliminating local dependency issues and providing consistent, reproducible builds. CloudShell's pre-configured AWS CLI and Docker support streamlined the container image creation and ECR push workflow.
Configured AWS ECS Fargate for serverless container orchestration with automatic task deployment. Implemented task definitions with proper resource allocation, environment variable management, and health checks for production-grade reliability and zero-downtime deployments.
This project demonstrates experience with:
Spring Boot, Spring MVC, dependency injection, RESTful API design, HTTP protocol
Relational modeling, JPA/Hibernate, entity relationships, query optimization, migrations
Layered architecture, separation of concerns, SOLID principles, design patterns
Unit testing, integration testing, test-driven development, code coverage
AWS cloud services (RDS, ECR, ECS, CloudShell, CodeBuild), Docker containerization, CI/CD pipelines, DNS automation (Namesilo API), IAM security, infrastructure as code
Error handling, validation, logging, documentation, code organization
git clone https://github.com/jc-gh25/MusicLibrary.git
cd music-library
mvn spring-boot:run
Access the API at http://localhost:8080/api and Swagger UI at http://localhost:8080/swagger-ui.html
For public access: Use the AWS production URL: http://project.jcarl.net/api
mvn test
mvn verify (runs all tests with detailed reporting)