Reservations Endpoints

Manage book hold requests. Students and staff can create and cancel their own reservations; librarians and admins can view all reservations and fulfill them.

Base Path: /api/v1/reservations

All endpoints require authentication (authenticate middleware applied globally on the router).

Create Reservation

POST /api/v1/reservations

Reserves an available copy of the specified book for the authenticated user. The copy's status is set to RESERVED and a 48-hour expiry window is created.

Authorization: Any authenticated user

Request Body

Success Response — 201 Created

{
  "reservation": {
    "_id": "...",
    "userId": "...",
    "bookCopyId": "...",
    "expiresAt": "2026-07-08T21:00:00.000Z",
    "status": "PENDING",
    "reservedAt": "2026-07-06T21:00:00.000Z"
  },
  "message": "Book reserved successfully"
}

Error Responses

Business Logic

1. Finds the first BookCopy with status: AVAILABLE for the given bookId
2. Sets the copy status to RESERVED
3. Creates a Reservation record with a 48-hour expiresAt timestamp
4. Returns the reservation object

Cancel Reservation

POST /api/v1/reservations/:id/cancel

Cancels a pending reservation owned by the authenticated user. Releases the reserved copy back to AVAILABLE status.

Authorization: Any authenticated user (own reservations only)

Path Parameters

Success Response — 200 OK

{
  "message": "Reservation cancelled successfully"
}

Error Responses

Fulfill Reservation

POST /api/v1/reservations/:id/fulfill

Converts a pending reservation into an active loan. This is a librarian/admin desk operation performed when the patron picks up the reserved book.

Authorization: ROLE_ADMIN, ROLE_LIBRARIAN

Path Parameters

Success Response — 200 OK

{
  "message": "Reservation fulfilled and book checked out",
  "transaction": {
    "_id": "...",
    "userId": "...",
    "bookCopyId": "...",
    "issuedAt": "2026-07-06T21:00:00.000Z",
    "dueDate": "2026-07-20T21:00:00.000Z",
    "renewalCount": 0
  }
}

Business Logic

1. Validates reservation exists and has PENDING status
2. Sets reservation status to FULFILLED
3. Sets the book copy status to CHECKED_OUT
4. Creates a Transaction (loan) with a 14-day due date
5. Sends a SUCCESS notification to the user: "Your reserved book has been successfully picked up"

Error Responses

List My Reservations

GET /api/v1/reservations/me

Returns all reservations belonging to the authenticated user, sorted by newest first. Includes populated book copy and book details.

Authorization: Any authenticated user

Success Response — 200 OK

{
  "reservations": [
    {
      "_id": "...",
      "userId": "...",
      "bookCopyId": {
        "_id": "...",
        "barcode": "BC-0001",
        "status": "RESERVED",
        "bookId": {
          "_id": "...",
          "title": "Introduction to Algorithms",
          "author": "Thomas Cormen"
        }
      },
      "status": "PENDING",
      "expiresAt": "2026-07-08T21:00:00.000Z",
      "reservedAt": "2026-07-06T21:00:00.000Z"
    }
  ]
}

List All Reservations

GET /api/v1/reservations

Returns all reservations across all users. Includes populated user info and book details.

Authorization: ROLE_ADMIN, ROLE_LIBRARIAN

Success Response — 200 OK

{
  "reservations": [
    {
      "_id": "...",
      "userId": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "rollNumber": "CS2024001"
      },
      "bookCopyId": {
        "barcode": "BC-0001",
        "bookId": {
          "title": "Introduction to Algorithms"
        }
      },
      "status": "PENDING",
      "expiresAt": "...",
      "reservedAt": "..."
    }
  ]
}

Route Summary