Skip to main content
POST
/
api
/
management
/
books
Create Book
curl --request POST \
  --url https://api.example.com/api/management/books \
  --header 'Content-Type: application/json' \
  --data '
{
  "isbn": "<string>",
  "title": "<string>",
  "description": "<string>",
  "coverImageUrl": "<string>",
  "authorIds": [
    {}
  ],
  "categoryId": 123
}
'
{
  "success": true,
  "data": {
    "id": 123,
    "isbn": "<string>",
    "title": "<string>",
    "description": "<string>",
    "coverImageUrl": "<string>",
    "authors": [
      {
        "id": 123,
        "name": "<string>"
      }
    ],
    "category": {
      "id": 123,
      "name": "<string>"
    }
  },
  "message": "<string>"
}

​
Endpoint

POST /api/management/books
Creates a new book in the library system.

​
Authentication

This endpoint requires authentication with the ADMIN role.

​
Request Body

​
isbn
string
required
International Standard Book Number. Must be a valid ISBN-10 or ISBN-13. The system automatically normalizes the ISBN by removing hyphens and spaces.Validation: Cannot be blank, must be valid ISBN format
​
title
string
required
Book titleValidation: Cannot be blank, must be between 2 and 255 characters
​
description
string
required
Detailed description of the bookValidation: Cannot be blank, maximum 1000 characters
​
coverImageUrl
string
URL to the book’s cover imageValidation: Must be a valid URL format if provided
​
authorIds
array
required
Array of author IDs to associate with the book. Books have a many-to-many relationship with authors.Validation: Cannot be empty, must contain at least one author IDExample: [1, 2, 3]
​
categoryId
long
required
ID of the category this book belongs to. Each book must belong to exactly one category.Validation: Cannot be null

​
Response

​
success
boolean
required
Indicates if the request was successful
​
data
object
required
The created book object
​
id
long
Unique identifier for the newly created book
​
isbn
string
International Standard Book Number in normalized format
​
title
string
Book title
​
description
string
Book description
​
coverImageUrl
string
URL to the book’s cover image
​
authors
array
Array of associated author objects
​
id
long
Author’s unique identifier
​
name
string
Author’s name
​
category
object
Category object
​
id
long
Category’s unique identifier
​
name
string
Category name
​
message
string
Optional message

​
Example Request

curl -X POST "http://localhost:8080/api/management/books" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "isbn": "978-0-13-468599-1",
    "title": "Effective Java",
    "description": "A comprehensive guide to Java programming best practices and design patterns. This third edition covers Java 7, 8, and 9.",
    "coverImageUrl": "https://example.com/covers/effective-java.jpg",
    "authorIds": [1],
    "categoryId": 2
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": 15,
    "isbn": "9780134685991",
    "title": "Effective Java",
    "description": "A comprehensive guide to Java programming best practices and design patterns. This third edition covers Java 7, 8, and 9.",
    "coverImageUrl": "https://example.com/covers/effective-java.jpg",
    "authors": [
      {
        "id": 1,
        "name": "Joshua Bloch"
      }
    ],
    "category": {
      "id": 2,
      "name": "Programming"
    }
  },
  "message": null
}

​
Error Responses

​
Validation Error (400)

{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": {
    "isbn": "Invalid ISBN format",
    "authorIds": "At least one author must be specified"
  }
}

​
Unauthorized (401)

{
  "success": false,
  "data": null,
  "message": "Authentication required"
}

​
Forbidden (403)

{
  "success": false,
  "data": null,
  "message": "Access denied. ADMIN role required."
}

​
Duplicate ISBN (400)

{
  "success": false,
  "data": null,
  "message": "A book with this ISBN already exists"
}

​
Notes

  • ISBN Normalization: The ISBN is automatically normalized before storage. For example, 978-0-13-468599-1 becomes 9780134685991
  • ISBN Validation: Both ISBN-10 and ISBN-13 formats are accepted and validated using the Hibernate validator
  • Author Relationship: Books have a many-to-many relationship with authors. You must provide at least one valid author ID
  • Category Relationship: Books have a many-to-one relationship with categories. Each book must belong to exactly one category
  • Uniqueness: The ISBN must be unique across all books in the system
  • Cover Image: The coverImageUrl field is optional but must be a valid URL if provided
  • Source: BookManagementController.java:24-27, BookCreateRequest.java:12-34, Book.java:26-30

Build docs developers (and LLMs) love

Get started for freeTalk to us