Skip to content

refactor(api): add filter support for records review endpoint

Laxman Reddy requested to merge refactor/api-next-for-review-filter-support into develop

Refactoring Request Template

Title

refactor(api): add advanced filter support for records review endpoint

Description

This merge request refactors the existing review retrieval flow by introducing a filter-based POST endpoint for fetching records under review workflows.

The goal of this refactor is to make the review API reusable across multiple frontend use cases such as:

  • Peer review infinite scroll
  • Proofreading workflows
  • Review queue filtering
  • Future moderation/review tools
  • Flexible record retrieval using structured filters

The existing /next-for-review endpoint had limited filtering capability and relied on query parameters, which became difficult to scale and validate as new filters were introduced.

This refactor introduces a clean request schema with validation support and dynamic query filtering while preserving backward compatibility.

Changes Implemented

Added New Endpoint

New Endpoint

POST /records/for-review

This endpoint accepts a structured request body for filtering review records.

Added Request Schema

Created a dedicated schema for validation and request parsing.

New Schema File

app/schemas/review.py

Request Structure

{ "filters": { "language": ["hindi"], "media_type": ["audio"], "category_ids": ["uuid-1", "uuid-2"], "has_unproofread_segments": true, "source_label": "Radio", "release_rights": "creator", "published_date": "2025-01-01" }, "limit": 20 }

Supported Filters

The endpoint now supports all required filters:

  • language
  • media_type
  • has_unproofread_segments
  • category_ids
  • source_label
  • release_rights
  • published_date

Refactor Improvements

Multi-Language Support

Language filtering now accepts multiple values.

Example:

"language": ["hindi", "english"]

Category OR Logic

Category filtering now uses OR logic.

Example:

"category_ids": ["uuid-a", "uuid-b"]

Returns records matching ANY supplied category.

Dynamic Filtering

Filters are only applied if present in the request.

This prevents unnecessary query constraints and keeps behavior flexible.

Enum Validation Added

Added validation for:

  • Language values
  • Media type values
  • Release rights values

Invalid values are safely filtered during schema validation.

Limit Validation

Request limit validation added.

Supported range:

1–50

Backward Compatibility

The existing endpoint remains unchanged.

Existing Endpoint Preserved

GET /records/next-for-review

No existing functionality was removed.

Existing review selection logic remains intact.

Files Added / Modified

Added

app/schemas/review.py

Modified

app/schemas/__init__.py app/api/v1/endpoints/records.py

Internal Logic Preserved

The following existing logic remains unchanged:

  • Review ordering
  • Record eligibility logic
  • Reviewer exclusion logic
  • Proofreading selection flow
  • Existing response structure
  • Existing review queue behavior

Validation & Verification

Verified:

  • No syntax issues
  • No import issues
  • No dead code introduced
  • No duplicate query logic
  • Response structure unchanged
  • Backward compatibility preserved
  • Enum-safe comparisons added
  • Query filtering works independently and together

Checklist

  • Refactor completed for scalability
    • No breaking changes introduced
    • New POST endpoint added
    • Request schema implemented
    • Dynamic filtering added
    • Category OR logic implemented
    • Multi-language filtering supported
    • Validation added for enums
    • Limit validation added
    • Existing endpoint preserved
    • Verification completed

Related Issue

Closes #99 (closed)

Merge request reports