feat(api): REST polish — cache fix, Location header, 409 detail (#530)

- Fix GET /players/ cache check: `if not players` → `if players is None`
  so empty collections are cached correctly
- Add Location header to POST /players/ 201 response pointing to
  /players/squadnumber/{squad_number} per RFC 7231 §7.1.2
- Add detail message to POST /players/ 409 response
- Add return type annotations to modified route handlers
- Add [Unreleased] subsections to CHANGELOG.md

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nanotaboada

CHANGELOG.md

@@ -42,6 +42,24 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+- `GET /players/` cache check changed from `if not players` to
+  `if players is None` so that an empty collection is cached correctly
+  instead of triggering a DB fetch on every request (#530)
+- `POST /players/` 409 response now includes a human-readable `detail`
+  message: "A Player with this squad number already exists." (#530)
+
+### Fixed
+
+- `POST /players/` 201 response now includes a `Location` header
+  pointing to the created resource at
+  `/players/squadnumber/{squad_number}` per RFC 7231 §7.1.2 (#530)
+
+### Removed
+
 ---
 
 ## [2.1.0 - Del Bosque] - 2026-03-31

routes/player_route.py

@@ -49,7 +49,8 @@
 async def post_async(
     player_model: Annotated[PlayerRequestModel, Body(...)],
     async_session: Annotated[AsyncSession, Depends(generate_async_session)],
-):
+    response: Response,
+) -> PlayerResponseModel:
     """
     Endpoint to create a new player.
 
@@ -68,14 +69,18 @@ async def post_async(
         async_session, player_model.squad_number
     )
     if existing:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT)
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="A Player with this squad number already exists.",
+        )
     player = await player_service.create_async(async_session, player_model)
     if player is None:  # pragma: no cover
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="Failed to create the Player due to a database error.",
         )
     await simple_memory_cache.clear(CACHE_KEY)
+    response.headers["Location"] = f"/players/squadnumber/{player.squad_number}"
     return player
 
 
@@ -92,7 +97,7 @@ async def post_async(
 async def get_all_async(
     response: Response,
     async_session: Annotated[AsyncSession, Depends(generate_async_session)],
-):
+) -> List[PlayerResponseModel]:
     """
     Endpoint to retrieve all players.
 
@@ -104,7 +109,7 @@ async def get_all_async(
     """
     players = await simple_memory_cache.get(CACHE_KEY)
     response.headers["X-Cache"] = "HIT"
-    if not players:
+    if players is None:
         players = await player_service.retrieve_all_async(async_session)
         await simple_memory_cache.set(CACHE_KEY, players, ttl=CACHE_TTL)
         response.headers["X-Cache"] = "MISS"

tests/test_main.py

@@ -178,6 +178,18 @@ def test_request_post_player_body_existing_response_status_conflict(client):
     assert response.status_code == 409
 
 
+def test_request_post_player_body_existing_response_body_detail(client):
+    """POST /players/ with existing player returns 409 with detail message"""
+    # Arrange
+    player = existing_player()
+    # Act
+    response = client.post(PATH, json=player.__dict__)
+    # Assert
+    assert (
+        response.json()["detail"] == "A Player with this squad number already exists."
+    )
+
+
 def test_request_post_player_body_nonexistent_response_status_created(client):
     """POST /players/ with nonexistent player returns 201 Created with a valid UUID"""
     # Arrange
@@ -275,3 +287,21 @@ def test_request_delete_player_squadnumber_existing_response_status_no_content(c
     response = client.delete(PATH + "squadnumber/" + str(player.squad_number))
     # Assert
     assert response.status_code == 204
+
+
+def test_request_post_player_body_nonexistent_response_header_location(client):
+    """POST /players/ with nonexistent player returns 201 with Location header"""
+    # Arrange
+    player = nonexistent_player()
+    try:
+        # Act
+        response = client.post(PATH, json=player.__dict__)
+        # Assert
+        assert response.status_code == 201
+        assert "Location" in response.headers
+        assert (
+            response.headers["Location"]
+            == f"/players/squadnumber/{player.squad_number}"
+        )
+    finally:
+        client.delete(PATH + "squadnumber/" + str(player.squad_number))