Project C: Reservation System

Description

Develop a RESTful API for a reservation system (hotels, restaurants, conference rooms, or events) allowing users to search, book, and manage their reservations.

---

Required Features

1. User Management

POST   /api/auth/register     - Registration
POST   /api/auth/login        - Login (returns JWT)
GET    /api/users/me          - User profile
PUT    /api/users/me          - Edit profile

User Entity:

• id, email, password, firstName, lastName, phone
• role (CUSTOMER, OWNER, ADMIN)
• createdAt

2. Resource Management

GET    /api/resources             - List resources (pagination, filters)
GET    /api/resources/{id}        - Resource detail
GET    /api/resources/search      - Advanced search
POST   /api/resources             - Create resource (OWNER/ADMIN)
PUT    /api/resources/{id}        - Edit resource
DELETE /api/resources/{id}        - Delete resource
GET    /api/owner/resources       - My resources (OWNER)

Resource Entity:

• id, name, description, type
• location (address, city, country)
• capacity, pricePerHour/pricePerNight
• amenities (List), images
• owner (User), active
• createdAt

3. Availabilities

GET    /api/resources/{id}/availability     - Availabilities
POST   /api/resources/{id}/availability     - Set availability (OWNER)
PUT    /api/availability/{id}               - Edit
DELETE /api/availability/{id}               - Delete
GET    /api/resources/{id}/calendar         - Monthly calendar

Availability Entity:

• id, resource, dayOfWeek or specificDate
• startTime, endTime
• available (boolean)

4. Reservations

POST   /api/reservations              - Create reservation
GET    /api/reservations              - My reservations
GET    /api/reservations/{id}         - Reservation detail
PUT    /api/reservations/{id}/cancel  - Cancel reservation
GET    /api/owner/reservations        - Reservations of my resources (OWNER)
PUT    /api/reservations/{id}/confirm - Confirm (OWNER)
PUT    /api/reservations/{id}/reject  - Reject (OWNER)

Reservation Entity:

• id, resource, user
• startDateTime, endDateTime
• status (PENDING, CONFIRMED, CANCELLED, COMPLETED)
• totalPrice, notes
• createdAt

5. Reviews and Ratings

POST   /api/reservations/{id}/review  - Leave a review
GET    /api/resources/{id}/reviews    - Resource reviews
GET    /api/reviews/my-reviews        - My reviews

Review Entity:

• id, reservation, user, resource
• rating (1-5), comment
• createdAt

---

Database Schema

users
├── id (PK)
├── email (UNIQUE)
├── password
├── first_name
├── last_name
├── phone
├── role
└── created_at

resources
├── id (PK)
├── name
├── description
├── type
├── address
├── city
├── country
├── capacity
├── price_per_unit
├── price_unit (HOUR, NIGHT, EVENT)
├── owner_id (FK)
├── active
└── created_at

resource_amenities
├── resource_id (FK)
└── amenity (STRING)

resource_images
├── id (PK)
├── resource_id (FK)
└── image_url

availability
├── id (PK)
├── resource_id (FK)
├── day_of_week (0-6)
├── specific_date (nullable)
├── start_time
├── end_time
└── available

reservations
├── id (PK)
├── resource_id (FK)
├── user_id (FK)
├── start_datetime
├── end_datetime
├── status
├── total_price
├── notes
└── created_at

reviews
├── id (PK)
├── reservation_id (FK)
├── user_id (FK)
├── resource_id (FK)
├── rating
├── comment
└── created_at

---

Business Rules

Availabilities

• Check availabilities before booking
• No overlap of confirmed reservations
• Owner sets available slots

Reservations

• Automatic calculation of total price
• Confirmation email (simulation)
• Cancellation possible up to X hours before

Reservation Statuses

PENDING -> CONFIRMED -> COMPLETED
       |-> REJECTED
       |-> CANCELLED (by customer)
CONFIRMED -> CANCELLED (by owner with justification)

Reviews

• One review per reservation
• Review possible only after COMPLETED
• Average rating calculated for each resource

Permissions

Role	Resources	Reservations	Reviews
ADMIN	CRUD all	View all	Moderate
OWNER	CRUD owns	Manage owns	-
CUSTOMER	Read all	CRUD owns	Create

---

Detailed Endpoints

Resource Search

GET /api/resources/search?city=Paris&date=2024-02-15&capacity=4&type=MEETING_ROOM
Authorization: Bearer <token>

Response 200:
{
  "content": [
    {
      "id": 1,
      "name": "Salle Eiffel",
      "description": "Modern meeting room with a view",
      "type": "MEETING_ROOM",
      "location": {
        "address": "123 Rue de Paris",
        "city": "Paris",
        "country": "France"
      },
      "capacity": 10,
      "pricePerHour": 50.00,
      "amenities": ["WIFI", "PROJECTOR", "WHITEBOARD"],
      "averageRating": 4.5,
      "reviewCount": 23,
      "availableSlots": [
        { "start": "09:00", "end": "12:00" },
        { "start": "14:00", "end": "18:00" }
      ]
    }
  ],
  "page": 0,
  "totalElements": 15
}

Create Reservation

POST /api/reservations
Authorization: Bearer <token>
Content-Type: application/json

{
  "resourceId": 1,
  "startDateTime": "2024-02-15T09:00:00",
  "endDateTime": "2024-02-15T12:00:00",
  "notes": "Marketing team meeting"
}

Response 201:
{
  "id": 1,
  "resource": {
    "id": 1,
    "name": "Salle Eiffel"
  },
  "user": {
    "id": 5,
    "firstName": "Marie",
    "lastName": "Dupont"
  },
  "startDateTime": "2024-02-15T09:00:00",
  "endDateTime": "2024-02-15T12:00:00",
  "status": "PENDING",
  "totalPrice": 150.00,
  "notes": "Marketing team meeting",
  "createdAt": "2024-01-20T10:30:00"
}

Calendar

GET /api/resources/1/calendar?month=2024-02
Authorization: Bearer <token>

Response 200:
{
  "resource": { "id": 1, "name": "Salle Eiffel" },
  "month": "2024-02",
  "days": [
    {
      "date": "2024-02-15",
      "slots": [
        { "start": "09:00", "end": "12:00", "status": "BOOKED" },
        { "start": "14:00", "end": "18:00", "status": "AVAILABLE" }
      ]
    },
    ...
  ]
}

Leave a Review

POST /api/reservations/1/review
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "comment": "Excellent room, very well equipped. I recommend!"
}

Response 201:
{
  "id": 1,
  "rating": 5,
  "comment": "Excellent room, very well equipped. I recommend!",
  "user": { "firstName": "Marie", "lastName": "D." },
  "createdAt": "2024-02-16T10:00:00"
}

---

Required Tests

Unit Tests

• ResourceService: search, availability check
• ReservationService: create, validate, cancel
• ReviewService: create, calculate average

Integration Tests

• Search with filters
• Reservation workflow
• Owner management endpoints

---

Bonus Points

Feature	Points
Email notifications	+3
Automatic reminders (@Scheduled)	+3
Calendar integration (iCal export)	+3
Payment system (simulation)	+5
Geographic search	+3
Owner dashboard	+5

---

Time Estimation

Task	Hours
Project setup and DB	2
Entities and repositories	5
Business services	8
REST Controllers	5
Security and permissions	5
Tests	6
Documentation	2
Bonus	4-8
Total	33-41

---

Back to Final Project