Complete mongo db integration for put /books/{id}) (#10)

* Add update_book_by_id which uses replace_one for full MongoDB doc replacement
* Implementing proper payload validation with validate_book_put_payload()
* Add/update tests with updated mocks/dummy data to reflect mongodb integration
* Sort missing fields so response is predictable
* Move shared constants to tests/test_data.py to reduce duplication (R0801)
* Move append_hostname test to separate file to fix pylint length
* Update openapi to reflect new PUT
* Update tests/test_app_utils_helper.py
unpack with '_' vs kwargs, indicate intentional throwaway
* Update app/datastore/mongo_helper.py
Use pymongo Collection type for book_collection annotation

Author: codesungrape

app/datastore/mongo_helper.py

@@ -1,7 +1,8 @@
 """Module containing pymongo helper functions."""
 
-from bson.objectid import ObjectId
+from bson.objectid import InvalidId, ObjectId
 from pymongo.cursor import Cursor
+from pymongo.collection import Collection
 
 
 def insert_book_to_mongo(book_data, collection):
@@ -65,7 +66,7 @@ def find_books(collection, query_filter=None, projection=None, limit=None) -> Cu
     return cursor
 
 
-def delete_book_by_id(book_collection, book_id):
+def delete_book_by_id(book_collection: Collection, book_id: str):
     """
     Soft delete book with given id
     Returns: The original document if found and updated, otherwise None.
@@ -81,3 +82,55 @@ def delete_book_by_id(book_collection, book_id):
     result = book_collection.find_one_and_update(filter_query, update_operation)
 
     return result
+
+# ------ PUT helpers ------------
+
+def validate_book_put_payload(payload: dict):
+    """
+    Validates the payload for a PUT request.
+    A PUT must contain all required fields and no extra fields
+
+    Returns:
+        A tuple: (is_valid, error_dictionary)
+        If valid, error_dictionary is None.
+    """
+    if not isinstance(payload, dict):
+        return False, {"error": "JSON payload must be a dictionary"}
+
+    required_fields = {"title", "synopsis", "author"}
+    payload_keys = set(payload.keys())
+
+    # Check 1: any missing fields?
+    missing_fields = required_fields - payload_keys
+    if missing_fields:
+        # Convert the set to a list and sort it.
+        sorted_missing = sorted(list(missing_fields))
+        return False, {"error": f"Missing required fields: {', '.join(sorted_missing)}"}
+
+    # Check 2: Any extra, unexpected fields?
+    extra_fields = payload_keys - required_fields
+    if extra_fields:
+        return False, {
+            "error": f"Unexpected fields provided: {', '.join(sorted(list(extra_fields)))}"
+        }
+
+    # If all checks pass:
+    return True, None
+
+
+def replace_book_by_id(book_collection, book_id, new_data):
+    """
+    Updates an ENTIRE book document in the database.
+    Returns True on success, False if book not found.
+    """
+    try:
+        object_id_to_update = ObjectId(book_id)
+
+    except InvalidId:
+        return False
+
+    # use $set operator to update the fields OR
+    # create them if they don't exist
+    result = book_collection.replace_one({"_id": object_id_to_update}, new_data)
+
+    return result.matched_count > 0

app/routes.py

@@ -1,18 +1,18 @@
 """Flask application module for managing a collection of books."""
 
-import copy
-
 from bson.objectid import InvalidId, ObjectId
 from flask import jsonify, request
 from pymongo.errors import ConnectionFailure
 from werkzeug.exceptions import HTTPException, NotFound
 
 from app.datastore.mongo_db import get_book_collection
-from app.datastore.mongo_helper import delete_book_by_id, insert_book_to_mongo
+from app.datastore.mongo_helper import (delete_book_by_id,
+                                        insert_book_to_mongo,
+                                        replace_book_by_id,
+                                        validate_book_put_payload)
 from app.services.book_service import fetch_active_books, format_books_for_api
 from app.utils.api_security import require_api_key
 from app.utils.helper import append_hostname
-from data import books
 
 
 def register_routes(app):  # pylint: disable=too-many-statements
@@ -200,52 +200,47 @@ def delete_book(book_id):
     def update_book(book_id):
         """
         Update a book by its unique ID using JSON from the request body.
-        Returns a single dictionary with the updated book's details.
+        Finds, replaces, and returns the single updated document.
         """
-        if not books:
+        # VALIDATION
+        request_body = request.get_json(silent=True)
+        if request_body is None:
+            return jsonify({"error": "Request must be valid JSON"}), 400
+
+        is_valid, error = validate_book_put_payload(request_body)
+        if not is_valid:
+            return jsonify(error), 400
+
+        # DATABASE INTERACTION
+        book_collection = get_book_collection()
+        if not book_collection:
             return jsonify({"error": "Book collection not initialized"}), 500
 
-        # check if request is json
-        if not request.is_json:
-            return jsonify({"error": "Request must be JSON"}), 415
-
-        # check request body is valid
-        request_body = request.get_json()
-        if not isinstance(request_body, dict):
-            return jsonify({"error": "JSON payload must be a dictionary"}), 400
-
-        # check request body contains required fields
-        required_fields = ["title", "synopsis", "author"]
-        missing_fields = [
-            field for field in required_fields if field not in request_body
-        ]
-        if missing_fields:
-            return {
-                "error": f"Missing required fields: {', '.join(missing_fields)}"
-            }, 400
+        was_replaced = replace_book_by_id(book_collection, book_id, request_body)
+        if not was_replaced:
+            return jsonify({"error": f"Book with ID '{book_id}' not found"}), 404
+
+        # RESPONSE HANDLING: Format API response
+        # replace_one doesn't return the document, so we must fetch it to return it.
+        updated_book = book_collection.find_one({"_id": ObjectId(book_id)})
+        # Convert ObjectId to string for the JSON response
+        updated_book["id"] = str(updated_book["_id"])
+
+        # Add HATEOAS links
+        host = request.host_url.strip("/")  # Use rstrip to avoid double slashes
+        book_obj_id = updated_book["id"]
+        updated_book["links"] = {
+            "self": f"/books/{book_obj_id}",
+            "reservations": f"/books/{book_obj_id}/reservations",
+            "reviews": f"/books/{book_obj_id}/reviews",
+        }
 
-        host = request.host_url
+        updated_book_with_hostname = append_hostname(updated_book, host)
 
-        # now that we have a book object that is valid, loop through books
-        for book in books:
-            if book.get("id") == book_id:
-                # update the book values to what is in the request
-                book["title"] = request.json.get("title")
-                book["synopsis"] = request.json.get("synopsis")
-                book["author"] = request.json.get("author")
-
-                # Add links exists as paths only
-                book["links"] = {
-                    "self": f"/books/{book_id}",
-                    "reservations": f"/books/{book_id}/reservations",
-                    "reviews": f"/books/{book_id}/reviews",
-                }
-                # make a deepcopy of the modified book
-                book_copy = copy.deepcopy(book)
-                book_with_hostname = append_hostname(book_copy, host)
-                return jsonify(book_with_hostname), 200
+        # Remove internal '_id' field
+        del updated_book_with_hostname["_id"]
 
-        return jsonify({"error": "Book not found"}), 404
+        return jsonify(updated_book_with_hostname), 200
 
     # ----------- CUSTOM ERROR HANDLERS ------------------
 

openapi.yml

@@ -303,10 +303,10 @@ paths:
     put:
       tags:
         - Books
-      summary: Update a book
+      summary: Update a book by replacement
       security:
         - ApiKeyAuth: []
-      description: Updates an existing book by its unique ID. The entire book object must be provided in the request body.
+      description: Updates an existing book by its unique ID. This is a full replacement operation (HTTP PUT). The request body must contain all required fields (`title`, `synopsis`, `author`) and no extra fields.
       operationId: updateBook
       parameters:
         - name: book_id
@@ -318,7 +318,7 @@ paths:
             pattern: '^[a-f\d]{24}$'
             example: "635f3a7e3a8e3bcfc8e6a1e0"
       requestBody:
-        description: Book object that needs to be updated.
+        description: A complete Book object to replace the existing one.
         required: true
         content:
           application/json:
@@ -332,15 +332,55 @@ paths:
               schema:
                 $ref: '#/components/schemas/BookOutput'
         '400':
-          $ref: '#/components/responses/BadRequest' 
+          description: |-
+            Bad Request. The request is invalid for one of the following reasons:
+            - The request body is not valid JSON.
+            - The JSON payload is missing required fields.
+            - The JSON payload contains unexpected fields.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleError'
+              examples:
+                missingFields:
+                  summary: Missing Fields Error
+                  value:
+                    error: "Missing required fields: author, synopsis"
+                extraFields:
+                  summary: Extra Fields Error
+                  value:
+                    error: "Unexpected fields provided: publication_year"
+                invalidJsonBody:
+                  summary: Invalid JSON
+                  value:
+                    error: "Request must be valid JSON"
         '401':
           $ref: '#/components/responses/Unauthorized' 
         '404':
-          $ref: '#/components/responses/NotFound' 
+          description: The book with the specified ID was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleError'
+              example:
+                error: "Book with ID '635f3a7e3a8e3bcfc8e6a1e1' not found" 
         '415':
-          $ref: '#/components/responses/UnsupportedMediaType' 
+          description: |-
+            Unsupported Media Type. The client sent a request with a Content-Type header other than `application/json`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleError'
+              example:
+                error: "Request must have Content-Type: application/json"
         '500':
-          $ref: '#/components/responses/InternalServerError' 
+          description: An internal server error occurred, likely related to the database connection.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SimpleError'
+              example:
+                error: "Book collection not initialized"
 
     # --------------------------------------------
 

tests/test_api_security.py

@@ -8,19 +8,8 @@
 import pytest
 from bson.objectid import ObjectId
 
-# A dictionary for headers to keep things clean
-HEADERS = {
-    "VALID": {"X-API-KEY": "test-key-123"},
-    "INVALID": {"X-API-KEY": "This-is-the-wrong-key-12345"},
-    "MISSING": {},
-}
-
-# A sample payload for POST/PUT requests
-DUMMY_PAYLOAD = {
-    "title": "A Test Book",
-    "synopsis": "A test synopsis.",
-    "author": "Tester McTestFace",
-}
+from tests.test_data import HEADERS, DUMMY_PAYLOAD
+
 
 # -------------- LOGGING --------------------------
 
@@ -125,42 +114,54 @@ def test_add_book_fails_if_api_key_not_configured_on_the_server(client, test_app
 # -------------- PUT --------------------------
 def test_update_book_succeeds_with_valid_api_key(monkeypatch, client):
     """Test successful book update with valid API key."""
+    # Arrange
+    test_book_id = "65a9a4b3f3a2c4a8c2b3d4e5"
 
-    # 1. Patch the books list
-    test_books = [
-        {
-            "id": "abc123",
-            "title": "Old Title",
-            "synopsis": "Old Synopsis",
-            "author": "Old Author",
-        }
-    ]
-    monkeypatch.setattr("app.routes.books", test_books)
-
-    # 2. Patch append_hostname to just return the book
-    monkeypatch.setattr("app.routes.append_hostname", lambda book, host: book)
+    mock_collection = MagicMock()
+    mock_collection.replace_one.return_value.matched_count = 1
+
+    expected_book_from_db = {
+        "_id": ObjectId(test_book_id),
+        # Use dictionary unpacking to merge our payload
+        **DUMMY_PAYLOAD,
+    }
+    mock_collection.find_one.return_value = expected_book_from_db
 
-    # 3. Call the endpoint with request details
-    response = client.put("/books/abc123", json=DUMMY_PAYLOAD, headers=HEADERS["VALID"])
+    # monkeypatcj to replace the real get_book_collection with a function
+    monkeypatch.setattr("app.routes.get_book_collection", lambda: mock_collection)
+
+    # ACT
+    response = client.put(
+        f"/books/{test_book_id}", json=DUMMY_PAYLOAD, headers=HEADERS["VALID"]
+    )
 
-    # 4. Assert response
+    # ASSERT 1
     assert response.status_code == 200
-    assert response.json["title"] == "A Test Book"
+    response_data = response.json
+    assert response_data["id"] == test_book_id
+    assert response_data["title"] == DUMMY_PAYLOAD["title"]
+    assert "links" in response_data
+    assert response_data["links"]["self"].endswith(f"/books/{test_book_id}")
 
+    # Assert 2
+    mock_collection.replace_one.assert_called_once()
+    mock_collection.replace_one.assert_called_with(
+        {"_id": ObjectId(test_book_id)}, DUMMY_PAYLOAD
+    )
+    mock_collection.find_one.assert_called_once()
+    mock_collection.find_one.assert_called_with({"_id": ObjectId(test_book_id)})
 
-def test_update_book_fails_with_missing_api_key(monkeypatch, client):
-    """Should return 401 if no API key is provided."""
 
-    monkeypatch.setattr("app.routes.books", [])
+def test_update_book_fails_with_missing_api_key(client):
+    """Should return 401 if no API key is provided."""
 
     response = client.put("/books/abc123", json=DUMMY_PAYLOAD)
 
     assert response.status_code == 401
     assert "API key is missing." in response.json["error"]["message"]
 
 
-def test_update_book_fails_with_invalid_api_key(client, monkeypatch):
-    monkeypatch.setattr("app.routes.books", [])
+def test_update_book_fails_with_invalid_api_key(client):
 
     response = client.put(
         "/books/abc123", json=DUMMY_PAYLOAD, headers=HEADERS["INVALID"]
@@ -170,17 +171,17 @@ def test_update_book_fails_with_invalid_api_key(client, monkeypatch):
     assert "Invalid API key." in response.json["error"]["message"]
 
 
-def test_update_book_fails_if_api_key_not_configured_on_the_server(
-    client, test_app, monkeypatch
-):
-    # ARRANGE: Remove API_KEY from the test_app config
-    monkeypatch.setattr("app.routes.books", [])
-    test_app.config.pop("API_KEY", None)
+# def test_update_book_fails_if_api_key_not_configured_on_the_server(
+#     client, test_app, monkeypatch
+# ):
+#     # ARRANGE: Remove API_KEY from the test_app config
+#     monkeypatch.setattr("app.routes.books", [])
+#     test_app.config.pop("API_KEY", None)
 
-    response = client.put("/books/abc123", json=DUMMY_PAYLOAD)
+#     response = client.put("/books/abc123", json=DUMMY_PAYLOAD)
 
-    assert response.status_code == 500
-    assert "API key not configured on the server." in response.json["error"]["message"]
+#     assert response.status_code == 500
+#     assert "API key not configured on the server." in response.json["error"]["message"]
 
 
 # -------------- DELETE --------------------------