Detailed API reference for book catalogue and copy management — list, create, update, delete books, and add physical copies.

Books Endpoints

Base path: /api/v1/books Authentication: All routes require a valid JWT token.

GET `/books`

Returns all books with optional search and category filtering.

Access Control

Allowed roles: Any authenticated user

Request

GET /api/v1/books?search=clean+code&categoryId=64c8f...
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
`search`	string	Regex search across `title`, `author`, and `isbn` fields
`categoryId`	string	Filter by category ObjectId

Response — `200 OK`

{
  "books": [
    {
      "_id": "64c8e...",
      "isbn": "978-0-13-235088-4",
      "title": "Clean Code",
      "author": "Robert C. Martin",
      "publisher": "Prentice Hall",
      "publicationYear": 2008,
      "categoryId": "64c8f...",
      "category": {
        "_id": "64c8f...",
        "name": "Software Engineering"
      },
      "copies": [
        {
          "_id": "64c9a...",
          "barcode": "B-10045",
          "status": "AVAILABLE",
          "location": "Shelf A-4"
        },
        {
          "_id": "64c9b...",
          "barcode": "B-10046",
          "status": "CHECKED_OUT",
          "location": "Shelf A-4"
        }
      ]
    }
  ]
}

Search Behavior

The search uses case-insensitive regex matching:

const searchRegex = new RegExp(search, 'i');
whereClause.$or = [
  { title: searchRegex },
  { author: searchRegex },
  { isbn: searchRegex }
];

GET `/books/:id`

Returns a single book with populated category and copies.

Request

GET /api/v1/books/64c8e...
Authorization: Bearer <token>

Response — `200 OK`

Same structure as individual book object in the list response.

Error Responses

Status	Body	When
`404`	`{ "error": "Book not found" }`	No book with that ID

POST `/books`

Creates a new book catalogue entry.

Access Control

Allowed roles: ROLE_ADMIN, ROLE_LIBRARIAN

Request

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

{
  "isbn": "978-3-16-148410-0",
  "title": "Design Patterns",
  "author": "Gang of Four",
  "publisher": "Addison-Wesley",
  "publicationYear": 1994,
  "categoryId": "64c8f..."
}

Field	Type	Required	Description
`isbn`	string	—	International Standard Book Number (unique)
`title`	string	✅	Book title
`author`	string	✅	Author name
`publisher`	string	—	Publisher name
`publicationYear`	number	—	Year of publication
`edition`	string	—	Edition identifier
`language`	string	—	Language
`pageCount`	number	—	Total pages
`description`	string	—	Synopsis
`coverImageUrl`	string	—	URL to cover image
`categoryId`	string	—	Category ObjectId

Response — `201 Created`

{
  "book": {
    "_id": "64c8e...",
    "isbn": "978-3-16-148410-0",
    "title": "Design Patterns",
    "author": "Gang of Four"
  }
}

PATCH `/books/:id`

Updates book metadata. Supports partial updates.

Access Control

Allowed roles: ROLE_ADMIN, ROLE_LIBRARIAN

Request

PATCH /api/v1/books/64c8e...
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Design Patterns: Elements of Reusable Object-Oriented Software",
  "edition": "1st"
}

Response — `200 OK`

Returns the updated book object.

DELETE `/books/:id`

Permanently deletes a book from the catalogue.

Access Control

Allowed roles: ROLE_ADMIN, ROLE_LIBRARIAN

Request

DELETE /api/v1/books/64c8e...
Authorization: Bearer <token>

Response — `200 OK`

{
  "message": "Book deleted successfully"
}

POST `/books/:id/copies`

Adds a physical copy (BookCopy) to an existing book.

Access Control

Allowed roles: ROLE_ADMIN, ROLE_LIBRARIAN

Request

POST /api/v1/books/64c8e.../copies
Authorization: Bearer <token>
Content-Type: application/json

{
  "barcode": "B-10047",
  "location": "Shelf A-4",
  "status": "AVAILABLE"
}

Field	Type	Required	Default	Description
`barcode`	string	✅	—	Unique physical barcode
`location`	string	—	`''`	Shelf location
`status`	string	—	`AVAILABLE`	Initial status enum

Response — `201 Created`

{
  "copy": {
    "_id": "64c9c...",
    "bookId": "64c8e...",
    "barcode": "B-10047",
    "status": "AVAILABLE",
    "location": "Shelf A-4"
  }
}

Error Responses

Status	Body	When
`404`	`{ "error": "Book not found" }`	Parent book doesn't exist

Books Endpoints

On this page