How to Use the API – Book Endpoints (/book, /books)

Books represent library items with metadata and pricing. This section covers how to list all books, retrieve a specific book, and perform CRUD operations by title. Endpoints are implemented in resources/book.py and registered in app.py .

📚 List All Books

Retrieves a JSON array of all books stored in the database. No authentication is required.

{
  "title": "List All Books",
  "description": "Fetches every book using BookModel.json().",
  "method": "GET",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/books",
  "headers": [],
  "queryParams": [],
  "pathParams": [],
  "bodyType": "none",
  "requestBody": "",
  "responses": {
    "200": {
      "description": "A JSON object containing a list of books.",
      "body": "{\n  \"books\": [\n    {\n      \"title\": \"Kalinga\",\n      \"price\": 200.0,\n      \"author\": \"Sapan Mohanty\",\n      \"isbn\": \"WER3455\",\n      \"release_date\": \"2020-12-12\"\n    }\n  ]\n}"
    }
  }
}

Response Schema

🔍 Get Book by Title (GET /book/)

Fetches a single book by its title. This endpoint is JWT-protected and requires an Authorization header containing a valid token .

{
  "title": "Authentication Required",
  "content": "Provide a valid JWT in the Authorization header."
}

{
  "title": "Get Book by Title",
  "description": "Retrieves details of a specific book. Protected by JWT.",
  "method": "GET",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/book/<title>",
  "headers": [
    {
      "key": "Authorization",
      "value": "JWT <token>",
      "required": true
    }
  ],
  "pathParams": [
    {
      "key": "title",
      "value": "The title of the book",
      "required": true
    }
  ],
  "bodyType": "none",
  "requestBody": "",
  "responses": {
    "200": {
      "description": "Book found",
      "body": "{\n  \"title\": \"Kalinga\",\n  \"price\": 200.0,\n  \"author\": \"Sapan Mohanty\",\n  \"isbn\": \"WER3455\",\n  \"release_date\": \"2020-12-12\"\n}"
    },
    "404": {
      "description": "Book not found",
      "body": "{\n  \"message\": \"book not found\"\n}"
    }
  }
}

➕ Create a New Book (POST /book/)

Adds a new book with the given title. Fails if a book with that title already exists .

• Path Parameter

  • title (string): Title of the new book.

• Request Body (JSON)

  • price (float, required)
  • store_id (int, required)
  • author (string, required)
  • isbn (string, required)
  • release_date (string, optional)

{
  "title": "Create Book",
  "description": "Creates a new book if title is unique.",
  "method": "POST",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/book/<title>",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json",
      "required": true
    }
  ],
  "pathParams": [
    {
      "key": "title",
      "value": "The title of the book",
      "required": true
    }
  ],
  "bodyType": "json",
  "requestBody": "{\n  \"price\": 150.5,\n  \"store_id\": 2,\n  \"author\": \"Jane Doe\",\n  \"isbn\": \"ABC1234\",\n  \"release_date\": \"2021-06-15\"\n}",
  "responses": {
    "201": {
      "description": "Book created successfully",
      "body": "{\n  \"title\": \"NewBook\",\n  \"price\": 150.5,\n  \"author\": \"Jane Doe\",\n  \"isbn\": \"ABC1234\",\n  \"release_date\": \"2021-06-15\"\n}"
    },
    "400": {
      "description": "Title already exists",
      "body": "{\n  \"message\": \"An book with title 'NewBook' already exists.\"\n}"
    },
    "500": {
      "description": "Database error",
      "body": "{\n  \"message\": \"An error occurred inserting the book.\"\n}"
    }
  }
}

✏️ Update or Create Book (PUT /book/)

Performs an upsert: updates the price if the book exists; otherwise creates it .

• Path Parameter

  • title (string): Title to update or create.

• Request Body (JSON – same as POST)

{
  "title": "Upsert Book",
  "description": "Updates price if exists; otherwise creates the book.",
  "method": "PUT",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/book/<title>",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json",
      "required": true
    }
  ],
  "pathParams": [
    {
      "key": "title",
      "value": "The title of the book",
      "required": true
    }
  ],
  "bodyType": "json",
  "requestBody": "{\n  \"price\": 175.0,\n  \"store_id\": 2,\n  \"author\": \"Jane Doe\",\n  \"isbn\": \"ABC1234\",\n  \"release_date\": \"2021-06-15\"\n}",
  "responses": {
    "200": {
      "description": "Book updated or created",
      "body": "{\n  \"title\": \"NewBook\",\n  \"price\": 175.0,\n  \"author\": \"Jane Doe\",\n  \"isbn\": \"ABC1234\",\n  \"release_date\": \"2021-06-15\"\n}"
    }
  }
}

🗑️ Delete a Book (DELETE /book/)

Removes the book with the specified title. Returns a success message or 404 if not found .

• Path Parameter
  • title (string): Title of the book to delete.

{
  "title": "Delete Book",
  "description": "Deletes a book by its title.",
  "method": "DELETE",
  "baseUrl": "http://localhost:5000",
  "endpoint": "/book/<title>",
  "headers": [],
  "pathParams": [
    {
      "key": "title",
      "value": "The title of the book",
      "required": true
    }
  ],
  "bodyType": "none",
  "requestBody": "",
  "responses": {
    "200": {
      "description": "Deletion successful",
      "body": "{\n  \"message\": \"Item deleted.\"\n}"
    },
    "404": {
      "description": "Book not found",
      "body": "{\n  \"message\": \"Item not found.\"\n}"
    }
  }
}

Data Model
The BookModel defines the schema and JSON representation of a book in models/book.py. Its json() method returns:

{
  "title": "string",
  "price": 0.0,
  "author": "string",
  "isbn": "string",
  "release_date": "string"
}

Fields correspond to database columns and are validated via reqparse in the resource parser .

Key Responsibilities

• Resource Handlers (resources/book.py): Parse input, enforce validation, handle database operations.
• Model Layer (models/book.py): Encapsulates data schema, persistence (save_to_db, delete_from_db), and lookup (find_by_title).

Best Practices

• Always include Content-Type: application/json for POST/PUT.
• Protect sensitive endpoints with JWT.
• Handle error responses gracefully on the client side.

This thorough guide helps you integrate, test, and extend the book-related REST API endpoints efficiently.