BookManagerApi

A production-grade Bookmark Management REST API built with Spring Boot — featuring JWT authentication, tagging, favorites, full-text search, visit tracking, and soft deletes.

🌐 Live API · 🖥 Frontend App · 📦 Backend Repo

---

Table of Contents

• Features
• Tech Stack
• Project Structure
• Authentication
• API Reference
• Sample Requests & Responses
• Getting Started
• Configuration
• Soft Delete Behavior
• Contributing
• License

---

Features

Feature	Details
🔐 JWT Authentication	Secure register & login flow
📌 Full CRUD	Create, read, update, and delete bookmarks
🗑 Soft Delete	Records marked deleted, never permanently removed
📄 Pagination & Sorting	Efficient list retrieval at scale
🔍 Full-text Search	Search across title and description
🏷 Tag Filtering	Many-to-many tag relationships
⭐ Favorites	Toggle bookmarks as favorites
📊 Visit Tracking	Track visit count and last visited timestamp
⚠️ Global Exception Handling	Consistent, structured error responses
📦 DTO Architecture	Clean separation of API and domain layers

---

Tech Stack

• Language: Java 17+
• Framework: Spring Boot, Spring Security, Spring Data JPA
• Database: PostgreSQL (compatible with any JPA-supported DB)
• Auth: JWT via JJWT (io.jsonwebtoken)
• ORM: Hibernate with soft delete support
• Utilities: Lombok, Jakarta Validation
• Build: Maven

---

Project Structure

com.dipanshu.BookManagerApi
├── config/ # Security & app configuration
├── controller/ # REST controllers
├── dto/ # Request & response DTOs
├── entity/ # JPA entities
├── exception/ # Global exception handling
├── mapper/ # Entity ↔ DTO mappers
├── repository/ # Spring Data repositories
└── security/ # JWT filter & utilities

---

Authentication

This API uses JWT (JSON Web Token) for stateless authentication.

1. Register or log in via the /auth endpoints to receive a token.
2. Include the token in all subsequent requests:

Authorization: Bearer <your-token>

Token validation is handled by a custom Spring Security filter. All bookmark endpoints require a valid token.

---

API Reference

Auth

Method	Endpoint	Description
POST	/auth/register	Register a new user
POST	/auth/login	Log in and receive a JWT

Bookmarks (JWT required)

Method	Endpoint	Description
POST	/bookmarks	Create a bookmark
GET	/bookmarks	List all bookmarks (paginated)
GET	/bookmarks/{id}	Get a bookmark by ID
PUT	/bookmarks/{id}	Update a bookmark
DELETE	/bookmarks/{id}	Soft delete a bookmark
GET	/bookmarks/search	Full-text search
GET	/bookmarks/tags/{tagName}	Filter by tag
PATCH	/bookmarks/{id}/favorite	Toggle favorite status
POST	/bookmarks/{id}/visit	Record a visit

---

Sample Requests & Responses

Register

// POST /auth/register
{
"username": "dipanshu",
"password": "password123"
}
// Response 200 OK
{
"token": "<jwt-token>",
"type": "Bearer"
}

Login

// POST /auth/login
{
"username": "dipanshu",
"password": "password123"
}
// Response 200 OK
{
"token": "<jwt-token>",
"type": "Bearer"
}

Create Bookmark

// POST /bookmarks
{
"title": "Google",
"url": "https://google.com",
"description": "Search Engine",
"tags": ["search", "tech"]
}

Search Bookmarks

GET /bookmarks/search?query=google&page=0&size=10

Error Response

{
"success": false,
"message": "Resource not found",
"errorCode": "RESOURCE_NOT_FOUND",
"timestamp": "2026-03-23T10:00:00"
}

---

Getting Started

Prerequisites

• Java 17+
• Maven
• PostgreSQL

1. Clone the Repository

git clone https://github.com/dipanshubatra/BookManagerApi.git
cd BookManagerApi

2. Configure the Database

Update src/main/resources/application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/bookmanager
spring.datasource.username=your_username
spring.datasource.password=your_password

3. Run the Application

mvn spring-boot:run

The API will be available at http://localhost:8080.

---

Configuration

Property	Description
jwt.secret	Secret key for signing JWT tokens
jwt.expiration	Token expiry in milliseconds (e.g. 3600000 = 1 hour)
spring.datasource.url	JDBC connection URL
spring.datasource.username	Database username
spring.datasource.password	Database password
spring.jpa.hibernate.ddl-auto	Schema strategy (update recommended for dev)

---

Soft Delete Behavior

Bookmarks are never permanently removed from the database. Deletion sets a flag using Hibernate's soft delete support, and all queries automatically exclude soft-deleted records. This preserves data integrity while keeping the API clean for end users.

---

Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to your branch (git push origin feature/my-feature)
5. Open a Pull Request

Please keep code style consistent and add relevant tests where applicable.

---

License

This project is licensed under the MIT License.

---

Made with ☕ by Dipanshu Batra