Streamline filter field names for captures / source_images

[coderabbitai]

Background

This is a follow-up task from PR #1127 to streamline filter field naming conventions on the backend side.

TODO Items

The following filter field names in ui/src/utils/useFilters.ts could be streamlined on the backend:

Capture Set Filters

Currently, there are three different field names for capture set filtering:

• collection (for viewing occurrences by capture set)
• source_image_collection (for viewing jobs by capture set)
• collections (for viewing captures by capture set)

Proposed: Standardize all three to use capture_set_id

Source Image Filters

Currently, there are two different field names for source image filtering:

• detections__source_image (for viewing Occurrences by capture)
• source_image_single (for viewing Jobs by capture)

Proposed: Standardize both to use capture_id

Reference

• PR: Update FE to use wording "capture sets" instead of "collections" #1127
• Comment: Update FE to use wording "capture sets" instead of "collections" #1127 (comment)

[coderabbitai]

Coding Plan

Summary

• Extend existing backward compatibility patterns (multi-parameter query_params lists and django-filter field_name mapping) rather than creating new mechanisms
• Convert simple filterset_fields to explicit FilterSet classes where needed to support parameter aliasing
• Keep all existing parameter names functional for backward compatibility, marked with TODO comments for future removal
• No database schema or model field changes required—only API layer filter parameter names are affected

Design Choices

Design Choice 1: Terminology Choice: `capture_set_id` and `capture_id` vs existing conventions

Options Considered:

1. Use capture_set_id and capture_id as explicitly proposed in the ticket
2. Use collection_id (already partially in use) and standardize around existing terminology

Chosen Option: 1

Rationale: Follow the ticket's explicit proposal since this represents an intentional decision from PR #1127 to align API filter parameter names with the conceptual model terminology (SourceImage = Capture, SourceImageCollection = CaptureSet).

💡 User Tips

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

Implementation Steps

Phase 1: Capture Set Filter Standardization

Add support for capture_set_id as the new standardized parameter name for filtering by SourceImageCollection across all relevant endpoints while maintaining backward compatibility with existing parameter names.

Task 1: Update Custom Filter Backends for Capture Set

Extend the existing custom filter backend classes to accept the new capture_set_id parameter alongside existing parameters.

• Update OccurrenceCollectionFilter in ami/main/api/views.py to add capture_set_id to the query_params list (currently has ["collection_id", "collection"])
• Update TaxonCollectionFilter in ami/main/api/views.py to add capture_set_id to its query param handling (currently uses collection)
• Add TODO comments marking collection and collection_id as deprecated, to be removed when UI is updated

Task 2: Create FilterSet for SourceImageViewSet

Replace the simple filterset_fields list with a custom FilterSet class that supports both the new capture_set_id parameter and the existing collections parameter.

• Create a new SourceImageFilterSet class in ami/main/api/views.py using django-filter's FilterSet
• Define capture_set_id filter with field_name="collections" to map the new parameter to the existing model field
• Include existing filter fields (event, deployment, deployment__project, collections, project, project_id) in Meta.fields for backward compatibility
• Update SourceImageViewSet to use filterset_class instead of filterset_fields

Task 3: Update JobFilterSet for Capture Set

Add a capture_set_id filter alias to the existing JobFilterSet that maps to the source_image_collection model field.

• Add explicit capture_set_id filter declaration in JobFilterSet in ami/jobs/views.py using filters.NumberFilter(field_name="source_image_collection")
• Keep source_image_collection in Meta.fields for backward compatibility
• Add TODO comment marking source_image_collection as deprecated filter name

🤖 Prompt for AI agents

This phase standardizes filtering by SourceImageCollection to use
`capture_set_id` as the primary parameter name across all relevant API endpoints
while maintaining backward compatibility with existing parameter names.

**Update Custom Filter Backends in `ami/main/api/views.py`:**
- Locate `OccurrenceCollectionFilter` class and add `"capture_set_id"` to the
`query_params` list (currently contains `["collection_id", "collection"]`)
- Locate `TaxonCollectionFilter` class and add `"capture_set_id"` to its query
param handling (currently uses `collection`)
- Add TODO comments to mark `collection` and `collection_id` as deprecated
parameters to be removed when UI is updated

**Create SourceImageFilterSet in `ami/main/api/views.py`:**
- Create a new `SourceImageFilterSet` class inheriting from django-filter's
FilterSet
- Add an explicit `capture_set_id` filter using
`filters.NumberFilter(field_name="collections")` to map the new parameter name
to the existing model field
- In the Meta class, specify the model and include all existing filter fields
for backward compatibility: `event`, `deployment`, `deployment__project`,
`collections`, `project`, `project_id`
- Update `SourceImageViewSet` to use `filterset_class = SourceImageFilterSet`
instead of the current `filterset_fields` list

**Update JobFilterSet in `ami/jobs/views.py`:**
- Add explicit `capture_set_id` filter declaration using
`filters.NumberFilter(field_name="source_image_collection")`
- Keep `source_image_collection` in the Meta.fields list for backward
compatibility
- Add TODO comment marking `source_image_collection` as a deprecated filter
parameter name

Phase 2: Capture Filter Standardization

Add support for capture_id as the new standardized parameter name for filtering by SourceImage (individual captures) across relevant endpoints while maintaining backward compatibility.

Task 1: Create FilterSet for OccurrenceViewSet

Replace the filterset_fields list with a custom FilterSet class that supports both the new capture_id parameter and the existing detections__source_image parameter.

• Create a new OccurrenceFilterSet class in ami/main/api/views.py
• Define capture_id filter with field_name="detections__source_image" to map the new parameter to the existing relationship path
• Include existing filter fields (event, deployment, determination__rank, detections__source_image) in Meta.fields for backward compatibility
• Update OccurrenceViewSet to use filterset_class instead of filterset_fields

Task 2: Update JobFilterSet for Capture

Add a capture_id filter alias to the JobFilterSet that maps to the source_image_single model field.

• Add explicit capture_id filter declaration in JobFilterSet using filters.NumberFilter(field_name="source_image_single")
• Keep source_image_single in Meta.fields for backward compatibility
• Add TODO comment marking source_image_single as deprecated filter name

🤖 Prompt for AI agents

This phase standardizes filtering by individual SourceImage (captures) to use
`capture_id` as the primary parameter name across relevant API endpoints while
maintaining backward compatibility with existing parameter names.

**Create OccurrenceFilterSet in `ami/main/api/views.py`:**
- Create a new `OccurrenceFilterSet` class inheriting from django-filter's
FilterSet
- Add an explicit `capture_id` filter using
`filters.NumberFilter(field_name="detections__source_image")` to map the new
parameter name to the existing relationship path
- In the Meta class, specify the model and include all existing filter fields
for backward compatibility: `event`, `deployment`, `determination__rank`,
`detections__source_image`
- Update `OccurrenceViewSet` to use `filterset_class = OccurrenceFilterSet`
instead of the current `filterset_fields` list

**Update JobFilterSet in `ami/jobs/views.py`:**
- Add explicit `capture_id` filter declaration using
`filters.NumberFilter(field_name="source_image_single")`
- Keep `source_image_single` in the Meta.fields list for backward compatibility
- Add TODO comment marking `source_image_single` as a deprecated filter
parameter name

Phase 3: Test Coverage and Documentation

Verify that the new standardized parameter names work correctly and update relevant tests.

Task 1: Add Tests for New Filter Parameters

Create or update tests to verify the new filter parameter names function correctly.

• Add test cases in ami/main/tests.py for capture_set_id filter on occurrences endpoint
• Add test cases for capture_set_id filter on captures endpoint
• Add test cases for capture_id filter on occurrences endpoint
• Add test cases in ami/jobs/tests.py for capture_set_id and capture_id filters on jobs endpoint
• Ensure tests verify both new and deprecated parameter names work identically

Task 2: Update Documentation Comments

Add clear documentation about the parameter name standardization.

• Add docstring comments to new FilterSet classes explaining the parameter name mapping and deprecation status
• Update any inline comments referencing the old parameter names to note the new standardized names
• Ensure TODO comments consistently indicate which parameters are deprecated and when they should be removed

🤖 Prompt for AI agents

This phase adds comprehensive test coverage for the new standardized filter
parameter names and updates documentation to clarify the parameter name mapping
and deprecation status.

**Add Tests in `ami/main/tests.py`:**
- Create test cases to verify `capture_set_id` filter works correctly on the
occurrences endpoint
- Create test cases to verify `capture_set_id` filter works correctly on the
captures (SourceImage) endpoint
- Create test cases to verify `capture_id` filter works correctly on the
occurrences endpoint
- For each new parameter, add tests that verify both the new standardized
parameter name and the deprecated parameter names return identical results

**Add Tests in `ami/jobs/tests.py`:**
- Create test cases to verify `capture_set_id` filter works correctly on the
jobs endpoint
- Create test cases to verify `capture_id` filter works correctly on the jobs
endpoint
- Ensure tests verify both new and deprecated parameter names work identically

**Update Documentation:**
- Add docstring comments to the newly created FilterSet classes
(`SourceImageFilterSet`, `OccurrenceFilterSet`) explaining the parameter name
mapping (e.g., `capture_set_id` maps to `collections` field) and which
parameters are deprecated
- Update inline comments that reference old parameter names to indicate the new
standardized names
- Ensure all TODO comments consistently indicate which parameters are deprecated
and note they should be removed when the UI is updated

Research

The project uses Django REST Framework with django-filter for API filtering. Filter implementations vary across endpoints: custom BaseFilterBackend classes (with query_params lists for multi-name support), filterset_fields lists for simple field filtering, and django-filter FilterSet classes for complex filtering. The codebase has an established pattern for backward compatibility where multiple query parameter names map to the same underlying filter using a list-based approach with TODO comments marking deprecated names. Database model fields (source_image_collection, source_image_single) should NOT be renamed—only API filter parameter names should change.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase standardizes filtering by SourceImageCollection to use
`capture_set_id` as the primary parameter name across all relevant API endpoints
while maintaining backward compatibility with existing parameter names.

**Update Custom Filter Backends in `ami/main/api/views.py`:**
- Locate `OccurrenceCollectionFilter` class and add `"capture_set_id"` to the
`query_params` list (currently contains `["collection_id", "collection"]`)
- Locate `TaxonCollectionFilter` class and add `"capture_set_id"` to its query
param handling (currently uses `collection`)
- Add TODO comments to mark `collection` and `collection_id` as deprecated
parameters to be removed when UI is updated

**Create SourceImageFilterSet in `ami/main/api/views.py`:**
- Create a new `SourceImageFilterSet` class inheriting from django-filter's
FilterSet
- Add an explicit `capture_set_id` filter using
`filters.NumberFilter(field_name="collections")` to map the new parameter name
to the existing model field
- In the Meta class, specify the model and include all existing filter fields
for backward compatibility: `event`, `deployment`, `deployment__project`,
`collections`, `project`, `project_id`
- Update `SourceImageViewSet` to use `filterset_class = SourceImageFilterSet`
instead of the current `filterset_fields` list

**Update JobFilterSet in `ami/jobs/views.py`:**
- Add explicit `capture_set_id` filter declaration using
`filters.NumberFilter(field_name="source_image_collection")`
- Keep `source_image_collection` in the Meta.fields list for backward
compatibility
- Add TODO comment marking `source_image_collection` as a deprecated filter
parameter name
===============================================================================

Task: 2

This phase standardizes filtering by individual SourceImage (captures) to use
`capture_id` as the primary parameter name across relevant API endpoints while
maintaining backward compatibility with existing parameter names.

**Create OccurrenceFilterSet in `ami/main/api/views.py`:**
- Create a new `OccurrenceFilterSet` class inheriting from django-filter's
FilterSet
- Add an explicit `capture_id` filter using
`filters.NumberFilter(field_name="detections__source_image")` to map the new
parameter name to the existing relationship path
- In the Meta class, specify the model and include all existing filter fields
for backward compatibility: `event`, `deployment`, `determination__rank`,
`detections__source_image`
- Update `OccurrenceViewSet` to use `filterset_class = OccurrenceFilterSet`
instead of the current `filterset_fields` list

**Update JobFilterSet in `ami/jobs/views.py`:**
- Add explicit `capture_id` filter declaration using
`filters.NumberFilter(field_name="source_image_single")`
- Keep `source_image_single` in the Meta.fields list for backward compatibility
- Add TODO comment marking `source_image_single` as a deprecated filter
parameter name
===============================================================================

Task: 3

This phase adds comprehensive test coverage for the new standardized filter
parameter names and updates documentation to clarify the parameter name mapping
and deprecation status.

**Add Tests in `ami/main/tests.py`:**
- Create test cases to verify `capture_set_id` filter works correctly on the
occurrences endpoint
- Create test cases to verify `capture_set_id` filter works correctly on the
captures (SourceImage) endpoint
- Create test cases to verify `capture_id` filter works correctly on the
occurrences endpoint
- For each new parameter, add tests that verify both the new standardized
parameter name and the deprecated parameter names return identical results

**Add Tests in `ami/jobs/tests.py`:**
- Create test cases to verify `capture_set_id` filter works correctly on the
jobs endpoint
- Create test cases to verify `capture_id` filter works correctly on the jobs
endpoint
- Ensure tests verify both new and deprecated parameter names work identically

**Update Documentation:**
- Add docstring comments to the newly created FilterSet classes
(`SourceImageFilterSet`, `OccurrenceFilterSet`) explaining the parameter name
mapping (e.g., `capture_set_id` maps to `collections` field) and which
parameters are deprecated
- Update inline comments that reference old parameter names to indicate the new
standardized names
- Ensure all TODO comments consistently indicate which parameters are deprecated
and note they should be removed when the UI is updated

💡 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 design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[mihow]

Nice thanks @annavik !