Implement `PATCH` method for partial player updates

[nanotaboada]

Problem

Currently, the API only supports PUT operations for updating player data, which requires sending the entire player object even when only one or two fields need to be modified. This is inefficient and doesn't follow REST best practices for partial resource updates. Users need a way to update specific player fields without having to provide all player data.

Proposed Solution

Implement HTTP PATCH method endpoints to allow partial updates of player resources. The API should accept a PlayerPartialUpdateRequest model and update only the fields provided in the request, leaving other fields unchanged.

Important constraint: Partial updates should allow modifying team-related data (position, squad number, team, league) but NOT personal details (firstName, middleName, lastName, dateOfBirth). Personal information should only be modified via PUT (full update).

Endpoint to implement:

• PATCH /players/squadnumber/{squad_number} - Update specific fields of a player by squad number

Note: We use squad number (natural identifier) instead of internal ID, as squad numbers are unique and user-facing.

Suggested Approach

1. Route Definition (routes/player_route.py)

• Add @api_router.patch("/players/squadnumber/{squad_number}") endpoint
• Include cache invalidation (call await simple_memory_cache.clear(CACHE_KEY))
• Add appropriate status codes (200 for success, 404 for not found, 400 for validation errors, 409 for conflicts)

2. Service Layer (services/player_service.py)

• Create async def patch_player_by_squad_number(async_session: AsyncSession, squad_number: int, update_data: dict) -> Optional[Player]
• If updating squad_number field itself, validate new squad_number doesn't create duplicates
• Handle partial data using exclude_unset=True in Pydantic model serialization

3. Model Definition (models/player_model.py)

• Refactor existing PlayerModel class to support Request/Response pattern with data transformations

• Create PlayerResponse class (for GET operations) with transformed properties to demonstrate data mapping:

  class PlayerResponse(BaseModel):
      full_name: str = Field(alias="fullName")  # Computed from firstName + middleName + lastName
      birth: str  # Formatted date string from dateOfBirth
      dorsal: int  # Maps from squadNumber (different naming)
      position: str
      club: str  # Maps from team (different naming)
      league: str
      starting11: str  # Transformed from bool to "Yes"/"No" string
  
      @field_validator('full_name', mode='before')
      @classmethod
      def compute_full_name(cls, v, info):
          # Compute from firstName, middleName, lastName in entity
          pass

• Create PlayerCreateRequest class (for POST - all fields except id)

• Create PlayerUpdateRequest class (for PUT - full replacement, all fields except id)

• Create PlayerPartialUpdateRequest class with only team-related fields as Optional:

  • squad_number: Optional[int]
  • position: Optional[str]
  • abbr_position: Optional[str]
  • team: Optional[str]
  • league: Optional[str]
  • starting11: Optional[bool]
  • Excludes: firstName, middleName, lastName, dateOfBirth (personal details)

• Implement mapper function or use Pydantic @computed_field to transform entity to response:

  • Concatenate firstName, middleName, lastName → fullName
  • Format dateOfBirth → birth (ISO date string)
  • Rename squadNumber → dorsal
  • Rename team → club
  • Convert starting11 bool → "Yes"/"No" string

• All models maintain camelCase aliasing with to_camel function

• Add appropriate validators for fields that require validation (e.g., squad number uniqueness)

4. Testing (tests/test_main.py)

• Test partial updates (single field, multiple fields)
• Test squad number uniqueness validation during PATCH
• Test 404 response for non-existent player
• Test cache invalidation after PATCH operations
• Use test data from player_stub.py

5. Code Style

• Format with Black: black .
• Lint with flake8: flake8
• Follow async/await patterns consistently
• Add proper type hints for all function parameters and return values

Acceptance Criteria

• Models refactored to use Request/Response pattern with data transformations:
  • PlayerResponse for GET operations with computed/transformed fields (fullName, birth, dorsal, club, starting11 as string)
  • Pydantic computed fields or mapper function transforms entity to response format
  • PlayerCreateRequest for POST operations
  • PlayerUpdateRequest for PUT operations
  • PlayerPartialUpdateRequest for PATCH operations (excludes personal details)
• Data mapping demonstrates Pydantic transformation capabilities
• PATCH endpoint /players/squadnumber/{squad_number} successfully updates team-related player fields
• Personal details (names, date of birth) cannot be modified via PATCH
• Only fields provided in request body are updated (other fields remain unchanged)
• Squad number uniqueness is validated when updating to a new squad number
• Appropriate HTTP status codes returned (200 OK, 404 Not Found, 400 Bad Request, 409 Conflict)
• Cache is invalidated after successful PATCH operations
• All tests pass with pytest -v
• Code coverage remains above 80% target
• Code formatted with Black and passes flake8 linting
• API documentation reflects new model names and PATCH endpoint in /docs

References

• RFC 5789 - PATCH Method for HTTP
• FastAPI Request Body - Optional Fields
• Pydantic - Partial Models

[coderabbitai]

🤖 CodeRabbit Planning

Planning is in progress. This will take a moment...

[coderabbitai]

🔗 Related PRs

#489 - refactor(tests): adopt action-oriented naming convention [merged]
#494 - Replace Postman collection with .rest file [merged]
#524 - refactor(api): use squad number for PUT and DELETE endpoints [merged]
#532 - feat(api): enforce squad number immutability on PUT [merged]
#548 - feat(api): REST polish — cache fix, Location header, 409 detail (#530) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Implement HTTP PATCH endpoint for partial player updates with squad number as identifier, and refactor the model layer to use Request/Response patterns with data transformations demonstrating Pydantic's capabilities (field renaming, computed concatenation, type conversion from bool to string).

Observations

The project is a FastAPI REST API for managing football player data with an async SQLAlchemy backend using SQLite. The architecture follows a three-layer pattern:

• Routes: FastAPI endpoints with SimpleMemoryCache
• Services: async CRUD operations with AsyncSession
• Schemas: SQLAlchemy ORM

Models are Pydantic-based with a MainModel base class providing automatic camelCase aliasing via to_camel. Current implementation only supports full updates via PUT, with no partial update capability or squad number uniqueness validation in the service layer.

Assumptions

Assumption 1: Response Model Transformation Strategy

Options Considered:

• Use Pydantic's @model_validator(mode='before') to intercept and transform ORM entity data during PlayerResponse instantiation
• Create explicit mapper functions that manually construct PlayerResponse from ORM entities
• Use @computed_field decorators on PlayerResponse

Chosen Option: 1

Rationale: The @model_validator(mode='before') approach is cleanest for one-way transformations from ORM entities to API responses, allowing us to intercept the raw entity data and reshape it before validation. This leverages Pydantic's validation lifecycle naturally.

Assumption 2: Service Layer Model Signature

Options Considered:

• Service methods accept Request Pydantic models and return ORM entities (maintain current pattern)
• Service methods accept dictionaries and return ORM entities (more flexible)
• Service methods accept/return Pydantic models throughout

Chosen Option: 1

Rationale: This maintains the existing pattern where services accept Pydantic models (Player(**player_model.model_dump())), perform ORM operations, and return SQLAlchemy entities. Routes handle conversion from ORM entities to Response models.

Assumption 3: PlayerModel Lifecycle

Options Considered:

• Delete PlayerModel entirely and replace all usage with new models
• Keep PlayerModel for backward compatibility and use alongside new models
• Keep simplified PlayerModel as internal service-layer model

Chosen Option: 2

Rationale: Keep PlayerModel temporarily to minimize disruption, but update routes to use the new Request/Response models. This allows gradual migration and easier rollback if needed. The PlayerModel essentially becomes an internal data transfer object between layers.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Model Layer Refactoring with Transformations

Create the new Request/Response model architecture with data transformations demonstrating field renaming, computation, and type conversion.

Task 1: Create Response Model with Transformations

Define PlayerResponse class that transforms database fields into a different API shape

• Create PlayerResponse class in models/player_model.py inheriting from MainModel
• Add transformed fields: full_name: str, birth: str, dorsal: int, position: str, club: str, league: str, starting11: str
• Implement @model_validator(mode='before') to transform incoming ORM entity data before field validation
• In the validator: concatenate first_name + middle_name + last_name → full_name, rename squad_number → dorsal, rename team → club, convert starting11 bool → "Yes"/"No" string, format date_of_birth → birth (ISO string)
• Maintain camelCase aliases through MainModel inheritance (fullName, etc.)

Task 2: Create Request Models for Different Operations

Define request models for POST, PUT, and PATCH operations with appropriate field constraints

• Create PlayerCreateRequest class in models/player_model.py with all player fields except id (id will be auto-generated)
• Create PlayerUpdateRequest class with all fields except id (for full replacement via PUT)
• Create PlayerPartialUpdateRequest class with only team-related fields as Optional: squad_number, position, abbr_position, team, league, starting11
• All request models inherit from MainModel for camelCase aliasing
• Ensure PlayerPartialUpdateRequest explicitly excludes personal detail fields (first_name, middle_name, last_name, date_of_birth)

🤖 Prompt for AI agents

Refactor model layer to use Request/Response patterns with data transformations.
Create the new model architecture demonstrating Pydantic's field renaming,
computed concatenation, and type conversion capabilities.

In `models/player_model.py`:
- Create `PlayerResponse` class inheriting from MainModel with transformed
fields: `full_name: str`, `birth: str`, `dorsal: int`, `position: str`, `club:
str`, `league: str`, `starting11: str`
- Add `@model_validator(mode='before')` to transform ORM entity data:
concatenate first_name + middle_name + last_name → full_name, rename
squad_number → dorsal, rename team → club, convert starting11 bool → "Yes"/"No"
string, format date_of_birth → birth (ISO string)
- Create `PlayerCreateRequest` class with all player fields except id
- Create `PlayerUpdateRequest` class with all fields except id
- Create `PlayerPartialUpdateRequest` class with only team-related fields as
Optional: squad_number, position, abbr_position, team, league, starting11
(exclude personal details)
- All models inherit from MainModel for camelCase aliasing

Phase 2: Service Layer Enhancement for Partial Updates

Extend the service layer with PATCH operation support and squad number conflict detection.

Task 1: Add Partial Update Service Method

Implement patch_by_squad_number method in services/player_service.py

• Create async def patch_by_squad_number_async(async_session: AsyncSession, squad_number: int, patch_model: PlayerPartialUpdateRequest) -> Optional[Player]
• Query player by squad_number using existing pattern: select(Player).where(Player.squad_number == squad_number)
• Return None if player not found (for 404 handling in route)
• Extract only set fields from patch_model using patch_model.model_dump(exclude_unset=True)
• Apply updates by iterating over provided fields and setting attributes on the ORM entity
• Call squad number validation helper if squad_number is being updated
• Commit with try-catch SQLAlchemyError and rollback on error (following existing pattern)
• Return updated Player entity

Task 2: Add Squad Number Uniqueness Validation

Create validation helper to prevent squad number conflicts during updates

• Create async def validate_squad_number_unique_async(async_session: AsyncSession, new_squad_number: int, current_player_id: int) -> bool in services/player_service.py
• Query for existing player with new_squad_number: select(Player).where(Player.squad_number == new_squad_number)
• Return True if no player found OR if found player has same ID as current_player_id
• Return False if different player already has this squad_number (indicating conflict)
• Use this helper in patch_by_squad_number_async before committing

🤖 Prompt for AI agents

Extend service layer with partial update support and squad number validation.
Implement PATCH operation that accepts PlayerPartialUpdateRequest and validates
squad number uniqueness.

In `services/player_service.py`:
- Add `patch_by_squad_number_async(async_session, squad_number, patch_model)`
method that queries player by squad_number, returns None if not found, extracts
only set fields using `model_dump(exclude_unset=True)`, applies updates to ORM
entity, calls squad number validation helper if squad_number is being updated,
commits with try-catch SQLAlchemyError and rollback on error, and returns
updated Player entity
- Add `validate_squad_number_unique_async(async_session, new_squad_number,
current_player_id)` helper that queries for existing player with
new_squad_number, returns True if no conflict (no player found OR same player
ID), returns False if different player has the squad_number
- Follow existing service layer patterns for async queries and error handling

Phase 3: Route Layer Updates and PATCH Endpoint

Update existing routes to use new models and implement the PATCH endpoint with proper error handling.

Task 1: Update Existing GET Routes to Use PlayerResponse

Modify GET endpoints to return transformed response data

• Update get_all_async in routes/player_route.py to use response_model=List[PlayerResponse]
• Update get_by_id_async to use response_model=PlayerResponse
• Update get_by_squad_number_async to use response_model=PlayerResponse
• After retrieving ORM entities from service, convert to PlayerResponse by instantiating: PlayerResponse.model_validate(player, from_attributes=True)
• For list responses, use list comprehension to convert each entity
• Cache operations remain unchanged but now cache PlayerResponse instances

Task 2: Update POST and PUT Routes to Use Request Models

Modify write endpoints to accept specific request models

• Update post_async in routes/player_route.py to accept player_model: PlayerCreateRequest = Body(...)
• Update put_async to accept player_model: PlayerUpdateRequest = Body(...)
• Service method calls remain the same since services accept Pydantic models
• Maintain existing cache invalidation with await simple_memory_cache.clear(CACHE_KEY)

Task 3: Implement PATCH Endpoint

Create new partial update endpoint following existing route patterns

• Add @api_router.patch("/players/squadnumber/{squad_number}", response_model=PlayerResponse, status_code=status.HTTP_200_OK, summary="Partially updates a Player by squad number", tags=["Players"])
• Inject squad_number: int = Path(...) and patch_model: PlayerPartialUpdateRequest = Body(...) and async_session: AsyncSession = Depends(generate_async_session)
• Call await player_service.patch_by_squad_number_async(async_session, squad_number, patch_model)
• Raise HTTPException(status_code=status.HTTP_404_NOT_FOUND) if service returns None
• If service raises SQLAlchemyError with unique constraint violation, catch and raise HTTPException(status_code=status.HTTP_409_CONFLICT)
• Invalidate cache with await simple_memory_cache.clear(CACHE_KEY)
• Convert returned ORM entity to PlayerResponse and return

🤖 Prompt for AI agents

Update route layer to use new Request/Response models and implement PATCH
endpoint. Modify existing endpoints and add new partial update capability with
proper error handling.

In `routes/player_route.py`:
- Update GET endpoints (`get_all_async`, `get_by_id_async`,
`get_by_squad_number_async`) to use `response_model=PlayerResponse` (or List),
convert ORM entities using `PlayerResponse.model_validate(player,
from_attributes=True)`
- Update `post_async` to accept `PlayerCreateRequest` and `put_async` to accept
`PlayerUpdateRequest`
- Add new PATCH endpoint at `/players/squadnumber/{squad_number}` with
PlayerResponse response model, inject squad_number Path parameter and
PlayerPartialUpdateRequest Body
- Call `patch_by_squad_number_async` service method, raise 404 if None returned,
catch SQLAlchemyError for unique constraint violations and raise 409 CONFLICT
- Invalidate cache and convert returned ORM entity to PlayerResponse
- Follow existing route patterns for dependency injection and error handling

Phase 4: Testing Updates and New Test Cases

Update existing tests for new response format and add comprehensive PATCH testing.

Task 1: Update Existing Test Assertions

Modify test expectations to match new PlayerResponse structure

• Update assertions in tests/test_main.py GET tests to expect transformed fields: fullName (not firstName/middleName/lastName), dorsal (not squadNumber), club (not team), starting11 as "Yes"/"No" string
• Update test_stub.py if needed to provide response data matching PlayerResponse schema
• Ensure all existing tests pass with new response structure

Task 2: Add PATCH Endpoint Tests

Create comprehensive test coverage for partial update functionality

• Add test in tests/test_main.py: test_given_valid_partial_data_when_patch_player_then_returns_200_and_updated_fields
• Test single field update (e.g., only position)
• Test multiple field update (e.g., position + squad_number + team)
• Add test: test_given_duplicate_squad_number_when_patch_player_then_returns_409_conflict
• Add test: test_given_nonexistent_squad_number_when_patch_player_then_returns_404_not_found
• Add test: test_given_patch_request_when_successful_then_cache_invalidated (verify X-Cache header on subsequent GET)
• Use existing_player() from player_stub.py for test data setup

🤖 Prompt for AI agents

Update existing tests for new PlayerResponse structure and add comprehensive
PATCH endpoint testing. Ensure all tests pass with transformed response fields.

In `tests/test_main.py`:
- Update GET test assertions to expect transformed fields: fullName (not
firstName/middleName/lastName), dorsal (not squadNumber), club (not team),
starting11 as "Yes"/"No" string
- Add test
`test_given_valid_partial_data_when_patch_player_then_returns_200_and_updated_fields`
for single and multiple field updates
- Add test
`test_given_duplicate_squad_number_when_patch_player_then_returns_409_conflict`
for conflict handling
- Add test
`test_given_nonexistent_squad_number_when_patch_player_then_returns_404_not_found`
for not found scenario
- Add test `test_given_patch_request_when_successful_then_cache_invalidated`
verifying X-Cache header on subsequent GET
- Use existing_player() from player_stub.py for test data setup
- Update test_stub.py if needed to match PlayerResponse schema

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Refactor model layer to use Request/Response patterns with data transformations.
Create the new model architecture demonstrating Pydantic's field renaming,
computed concatenation, and type conversion capabilities.

In `models/player_model.py`:
- Create `PlayerResponse` class inheriting from MainModel with transformed
fields: `full_name: str`, `birth: str`, `dorsal: int`, `position: str`, `club:
str`, `league: str`, `starting11: str`
- Add `@model_validator(mode='before')` to transform ORM entity data:
concatenate first_name + middle_name + last_name → full_name, rename
squad_number → dorsal, rename team → club, convert starting11 bool → "Yes"/"No"
string, format date_of_birth → birth (ISO string)
- Create `PlayerCreateRequest` class with all player fields except id
- Create `PlayerUpdateRequest` class with all fields except id
- Create `PlayerPartialUpdateRequest` class with only team-related fields as
Optional: squad_number, position, abbr_position, team, league, starting11
(exclude personal details)
- All models inherit from MainModel for camelCase aliasing
===============================================================================

Task: 2

Extend service layer with partial update support and squad number validation.
Implement PATCH operation that accepts PlayerPartialUpdateRequest and validates
squad number uniqueness.

In `services/player_service.py`:
- Add `patch_by_squad_number_async(async_session, squad_number, patch_model)`
method that queries player by squad_number, returns None if not found, extracts
only set fields using `model_dump(exclude_unset=True)`, applies updates to ORM
entity, calls squad number validation helper if squad_number is being updated,
commits with try-catch SQLAlchemyError and rollback on error, and returns
updated Player entity
- Add `validate_squad_number_unique_async(async_session, new_squad_number,
current_player_id)` helper that queries for existing player with
new_squad_number, returns True if no conflict (no player found OR same player
ID), returns False if different player has the squad_number
- Follow existing service layer patterns for async queries and error handling
===============================================================================

Task: 3

Update route layer to use new Request/Response models and implement PATCH
endpoint. Modify existing endpoints and add new partial update capability with
proper error handling.

In `routes/player_route.py`:
- Update GET endpoints (`get_all_async`, `get_by_id_async`,
`get_by_squad_number_async`) to use `response_model=PlayerResponse` (or List),
convert ORM entities using `PlayerResponse.model_validate(player,
from_attributes=True)`
- Update `post_async` to accept `PlayerCreateRequest` and `put_async` to accept
`PlayerUpdateRequest`
- Add new PATCH endpoint at `/players/squadnumber/{squad_number}` with
PlayerResponse response model, inject squad_number Path parameter and
PlayerPartialUpdateRequest Body
- Call `patch_by_squad_number_async` service method, raise 404 if None returned,
catch SQLAlchemyError for unique constraint violations and raise 409 CONFLICT
- Invalidate cache and convert returned ORM entity to PlayerResponse
- Follow existing route patterns for dependency injection and error handling
===============================================================================

Task: 4

Update existing tests for new PlayerResponse structure and add comprehensive
PATCH endpoint testing. Ensure all tests pass with transformed response fields.

In `tests/test_main.py`:
- Update GET test assertions to expect transformed fields: fullName (not
firstName/middleName/lastName), dorsal (not squadNumber), club (not team),
starting11 as "Yes"/"No" string
- Add test
`test_given_valid_partial_data_when_patch_player_then_returns_200_and_updated_fields`
for single and multiple field updates
- Add test
`test_given_duplicate_squad_number_when_patch_player_then_returns_409_conflict`
for conflict handling
- Add test
`test_given_nonexistent_squad_number_when_patch_player_then_returns_404_not_found`
for not found scenario
- Add test `test_given_patch_request_when_successful_then_cache_invalidated`
verifying X-Cache header on subsequent GET
- Use existing_player() from player_stub.py for test data setup
- Update test_stub.py if needed to match PlayerResponse schema

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!