Skip to main content

​
Overview

As a Trippins administrator, you have oversight of all reservations in the system. This includes viewing complete reservation details, modifying bookings, managing the valorated (review) status, and canceling reservations when necessary.
Admin-level access is required to view and manage all reservations. Regular users can only see their own bookings.

​
Reservation Entity Structure

The Reservation entity manages the booking lifecycle from creation through checkout and review. 
@Entity
public class Reservation {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @Column(name = "check_in", nullable = false, length = 9)
    private Date check_in;

    @Column(name = "check_out", nullable = false, length = 9)
    private Date check_out;

    @Column(name="valorated", length = 1)
    private boolean valorated;

    @ManyToOne
    @JoinColumn(name = "Client_ID", referencedColumnName = "dni", nullable = false)
    private User client;

    @ManyToOne
    @JoinColumn(name = "Hotel_Code", referencedColumnName = "code", nullable = false)
    private Housing housing;

    @ManyToOne
    @JoinColumn(name = "Hotel_Name", referencedColumnName = "name", nullable = false)
    private Housing housing_name;
}

​
Key Fields

​
id
Integer
Auto-generated unique identifier for the reservation
​
check_in
Date
The reservation start date (guest arrival)
​
check_out
Date
The reservation end date (guest departure)
​
valorated
boolean
Indicates whether the guest has left a review for this stay. Set to false by default.
​
client
User
Many-to-one relationship with the User entity representing the guest
​
housing
Housing
Many-to-one relationship with the Housing entity representing the booked property

​
Admin Workflows

​
Viewing All Reservations

Administrators can retrieve a complete list of all reservations across the platform. 
curl -X GET "https://api.trippins.com/v1/api/reservations" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Response Example: 
[
  {
    "id": 1,
    "checkIn": "2026-03-19",
    "checkOut": "2026-03-24",
    "valorated": false,
    "clientDni": "12345678A",
    "housingCode": 1,
    "housingName": "Hotel Madrid"
  },
  {
    "id": 2,
    "checkIn": "2026-03-19",
    "checkOut": "2026-03-24",
    "valorated": true,
    "clientDni": "12345678A",
    "housingCode": 1,
    "housingName": "Hotel Madrid"
  }
]

​
Viewing a Specific Reservation

Retrieve detailed information about a single reservation by its ID. 
curl -X GET "https://api.trippins.com/v1/api/reservations/1" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Returns 200 OK with the reservation details, or 404 Not Found if the reservation doesn’t exist

​
Filtering Unreviewed Reservations

Track which guests haven’t yet left reviews for their stays using the valorated filter. 
public Page<ReservationDTO> findByValoratedFalse(Pageable pageable) {
    Page<Reservation> reservations = reservationRepository.findByValoratedFalse(pageable);

    return reservations.map(reserves -> {
        ReservationDTO dto = new ReservationDTO();
        dto.setCheckIn(reserves.getCheck_in());
        dto.setCheckOut(reserves.getCheck_out());
        dto.setClientDni(reserves.getID_cliente().getDni());
        dto.setHousingCode(reserves.getHousing().getCode());
        dto.setHousingName(reserves.getHousing().getName());
        dto.setValorated(false);
        dto.setId(reserves.getId());
        return dto;
    });
}
Use this endpoint to send review reminder emails to guests who completed their stay but haven’t left feedback

​
Creating a Reservation (Admin Override)

Administrators can create reservations on behalf of users, useful for phone bookings or special arrangements.
1

Gather Required Information

Collect the client DNI, housing code, check-in date, and check-out date.
2

Submit the Reservation

curl -X POST "https://api.trippins.com/v1/api/reservations" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkIn": "2026-04-15",
    "checkOut": "2026-04-20",
    "valorated": false,
    "clientDni": "87654321B",
    "housingCode": 5,
    "housingName": "Hotel London"
  }'
3

Confirm Creation

The API returns the created reservation with its auto-generated ID:
{
  "id": 3,
  "checkIn": "2026-04-15",
  "checkOut": "2026-04-20",
  "valorated": false,
  "clientDni": "87654321B",
  "housingCode": 5,
  "housingName": "Hotel London"
}

public ReservationDTO createReservation(ReservationDTO reservation) {
    Reservation newReservation = new Reservation(
        reservation.getId(), 
        userRepository.findById(reservation.getClientDni()).get(),
        housingRepository.findByCode(reservation.getHousingCode()).get(),
        reservation.getCheckIn(),
        reservation.getCheckOut(),
        reservation.isValorated()
    );
    reservationRepository.save(newReservation);
    return new ReservationDTO(newReservation);
}

​
Modifying an Existing Reservation

Update reservation details such as dates, housing, or review status. 
curl -X PUT "https://api.trippins.com/v1/api/reservations/1" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "checkIn": "2026-03-20",
    "checkOut": "2026-03-25",
    "valorated": false,
    "clientDni": "12345678A",
    "housingCode": 2,
    "housingName": "Hotel Barcelona"
  }'
When modifying check-in/check-out dates, ensure there are no conflicting reservations for the same housing

​
Marking a Reservation as Reviewed

When a guest completes a review, update the valorated flag to track completion. 
public void acceptReservation(Integer id) {
    Reservation reservation = reservationRepository.findById(id).get();
    reservation.setValorated(true);
    reservationRepository.save(reservation);
}
This flag helps track engagement metrics and can trigger automated follow-up workflows

​
Canceling a Reservation

Remove a reservation from the system when canceled by the guest or admin. 
curl -X DELETE "https://api.trippins.com/v1/api/reservations/1" \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Returns 204 No Content on successful deletion. This operation is permanent.

​
User-Specific Reservations

​
Viewing Reservations by Client

Retrieve all reservations for a specific user by their DNI. 
public List<ReservationDTO> getReservationsByOwner(User user) {
    List<Reservation> reservations = 
        reservationRepository.findByClientDni(user.getDni());

    List<ReservationDTO> reservationDTOs = new ArrayList<>();
    for (Reservation reservation : reservations) {
        reservationDTOs.add(new ReservationDTO(reservation));
    }
    return reservationDTOs;
}
Use Cases:
  • Customer support inquiries
  • Analyzing booking patterns
  • Resolving disputes or issues
  • Generating user activity reports

​
Reservation Lifecycle

1

Reservation Creation

Guest selects housing, check-in/check-out dates, and confirms booking. valorated is set to false.
2

Active Reservation

Guest checks in on the check_in date. Reservation is active until check_out date.
3

Post-Stay Period

After check-out, the reservation remains in the system with valorated = false.
4

Review Submission

Guest leaves a review. Admin or system updates valorated = true.
5

Completed

Reservation is marked as fully completed with review on file.

​
Data Initialization

The system includes a reservation initializer for development and testing:
ReservationService.java
public void initializeReservations() {
    Optional<User> defUser = userRepository.findByName("Pepe");
    Optional<Housing> defHousing = housingRepository.findById(1);

    Calendar calendar = Calendar.getInstance();
    calendar.add(Calendar.DAY_OF_MONTH, 10); // Check-in in 10 days
    Date checkIn1 = new Date(calendar.getTimeInMillis());

    calendar.add(Calendar.DAY_OF_MONTH, 5); // Check-out 5 days after check-in
    Date checkOut1 = new Date(calendar.getTimeInMillis());

    List<Reservation> prechargedReservations = Arrays.asList(
        new Reservation(1, (Client) defUser.get(), defHousing.get(), checkIn1, checkOut1),
        new Reservation(2, (Client) defUser.get(), defHousing.get(), checkIn1, checkOut1)
    );

    reservationRepository.saveAll(prechargedReservations);
}
This method is called during application startup via @PostConstruct or similar initialization hooks

​
Security and Permissions

​
Admin-Only Access

Reservation management endpoints require the ADMIN role:
SecurityConfiguration.java
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/v1/api/reservations/**").hasRole("ADMIN")
        .requestMatchers("/admin/**").hasRole("ADMIN")
        // ...
    );
    return http.build();
}

​
JWT Authentication

All operations require a valid JWT token with admin privileges: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Non-admin users attempting to access reservation management endpoints receive 403 Forbidden

​
API Reference

​
Reservation Management Endpoints

​
GET /v1/api/reservations
GET
Retrieve all reservations in the systemSecurity: Requires ADMIN roleResponse: 200 OK with array of ReservationDTO objects
​
GET /v1/api/reservations/{id}
GET
Get a specific reservation by IDSecurity: Requires ADMIN roleParameters:
  • id (path) - Reservation ID (e.g., 1)
Response: 200 OK with ReservationDTO object
​
POST /v1/api/reservations
POST
Create a new reservationSecurity: Requires ADMIN roleBody: ReservationDTO object (ID is auto-generated)Response: 201 Created with created ReservationDTO
​
PUT /v1/api/reservations/{id}
PUT
Update an existing reservationSecurity: Requires ADMIN roleParameters:
  • id (path) - Reservation ID to update
Body: Complete ReservationDTO objectResponse: 200 OK with updated ReservationDTO
​
DELETE /v1/api/reservations/{id}
DELETE
Cancel and delete a reservationSecurity: Requires ADMIN roleParameters:
  • id (path) - Reservation ID to delete
Response: 204 No Content

​
Best Practices

Always ensure check_out is after check_in. Implement validation logic to prevent invalid date ranges.
Before creating or modifying reservations, verify the housing is available for the requested dates.
Monitor the valorated flag to identify guests who haven’t left reviews. Use this for engagement campaigns.
When deleting a reservation, consider the impact on reviews and payment records. Archive instead of delete when possible.
Log all admin modifications to reservations for accountability and dispute resolution.

​
Troubleshooting

Cause: The reservation ID doesn’t exist in the databaseSolution: Verify the ID is correct using the GET all reservations endpoint
Cause: Referenced client or housing doesn’t existSolution: Ensure the clientDni and housingCode correspond to existing User and Housing records
Cause: Review hasn’t been submitted yetSolution: Only set valorated = true after the corresponding review is created in the Review entity
Cause: Incorrect date format in API requestsSolution: Use ISO 8601 date format: YYYY-MM-DD (e.g., “2026-03-19”)

​
Reporting and Analytics

​
Key Metrics to Track

Total Reservations

Monitor overall booking volume

Pending Reviews

Track reservations with valorated = false

Average Stay Duration

Calculate check_out - check_in across bookings

Top Properties

Identify housing with most reservations

​
Sample Query for Analytics

// Get all reservations for a specific date range
List<Reservation> reservations = reservationRepository
    .findByCheckInBetween(startDate, endDate);

// Calculate average stay duration
double avgDuration = reservations.stream()
    .mapToLong(r -> ChronoUnit.DAYS.between(
        r.getCheck_in().toLocalDate(), 
        r.getCheck_out().toLocalDate()
    ))
    .average()
    .orElse(0.0);

Build docs developers (and LLMs) love

Get started for freeTalk to us