Feature Implementation Plan: Standardize API Filtering Parameters (Backend)

📋 Todo Checklist

• [ ] Update the /api/coffee-beans endpoint to change roasterId to roasterIds[].
• [ ] Update the /api/coffee-beans endpoint to change countryId to countryIds[].
• [ ] Update the api_filters.yaml configuration to reflect these changes.
• [ ] Update the OpenAPI documentation (annotations) for the endpoint.
• [ ] Update integration tests to use the new parameters.
• [ ] Final Review and Testing

🔍 Analysis & Investigation

Codebase Structure

• Metadata Source: The OpenAPI annotations in src/Controller/Api/CoffeeBeanController.php for roasterId and countryId will be modified.
• Filtering Logic: The configuration keys in config/packages/api_filters.yaml will be updated to match the new parameter names and types.

Current Architecture & Problem

• Problem: The API is inconsistent. Most ID-based filters accept arrays (e.g., speciesIds[]), but roasterId and countryId only accept a single value. This makes the API less predictable.
• Solution: This plan standardizes all ID-based filters to be plural and accept arrays. This is a breaking change that will significantly improve API consistency. There is no requirement for backward compatibility.

Dependencies & Integration Points

• FilterService: The FilterService is already capable of handling uuid_array types, so no changes are needed in the service itself, only in its configuration.
• NelmioApiDocBundle: Correcting the annotations in the controller is crucial for ensuring the /api/filters/metadata endpoint and the OpenAPI documentation accurately reflect the API's behavior.

📝 Implementation Plan

Prerequisites

• No new external dependencies are required.

Step-by-Step Implementation

1. Update CoffeeBeanController Annotations

   • Files to modify: src/Controller/Api/CoffeeBeanController.php
   • Changes needed:
     • Locate the #[OA\Parameter] for roasterId.
       • Change the name from 'roasterId' to 'roasterIds[]'.
       • Update the schema to be new OA\Schema(type: 'array', items: new OA\Items(type: 'string', format: 'uuid')).
       • Add style: 'form', explode: true.
     • Locate the #[OA\Parameter] for countryId.
       • Change the name from 'countryId' to 'countryIds[]'.
       • Update the schema to be new OA\Schema(type: 'array', items: new OA\Items(type: 'string', format: 'uuid')).
       • Add style: 'form', explode: true.

2. Update Filter Configuration

   • Files to modify: config/packages/api_filters.yaml
   • Changes needed:
     • In the api_filters section for App\Entity\CoffeeBean:
     • Rename the roasterId key to roasterIds.
     • Change its type from 'uuid' to 'uuid_array'.
     • Update the field to point to the 'roaster' relationship.
     • Rename the countryId key to countryIds.
     • Change its type from 'uuid' to 'uuid_array'.
     • Update the field to point to the 'country' relationship.

Testing Strategy

• Integration Tests:
  • Find and update any existing integration tests for /api/coffee-beans that use roasterId or countryId and change them to use the new roasterIds[] and countryIds[] parameters.
  • Add a new test case that passes multiple roasterIds[] to ensure the array filtering works correctly.
  • Add a new test case that passes multiple countryIds[] to ensure the array filtering works correctly.
  • Update the test for /api/filters/metadata to assert that the keys are now roasterIds and countryIds and their type is array.

🎯 Success Criteria

• The roasterId and countryId parameters are successfully replaced by roasterIds[] and countryIds[] on the /api/coffee-beans endpoint.
• The API correctly filters by an array of roaster and country IDs.
• The /api/filters/metadata endpoint and the OpenAPI documentation accurately reflect these changes.
• All ID-based filters on the /api/coffee-beans endpoint are now consistently array-based.