Skip to content

Feat/api v3 filters no reflect#4146

Closed
tothandras wants to merge 5 commits intomainfrom
feat/api-v3-filters-no-reflect
Closed

Feat/api v3 filters no reflect#4146
tothandras wants to merge 5 commits intomainfrom
feat/api-v3-filters-no-reflect

Conversation

@tothandras
Copy link
Copy Markdown
Contributor

@tothandras tothandras commented Apr 15, 2026

Overview

Fixes #(issue)

Notes for reviewer

Summary by CodeRabbit

Release Notes

  • New Features

    • Enhanced API filtering with support for advanced operators (equality, ranges, pattern matching, existence checks)
    • Improved error responses with detailed validation feedback on invalid query parameters
    • Support for filtering by multiple fields on list endpoints
  • Bug Fixes

    • Corrected datetime range filter operators in filter specifications
    • Fixed filter validation and error handling in customer and pricing list endpoints
  • Documentation

    • Added comprehensive API specification guidance covering filtering, CRUD operations, pagination, naming conventions, and error handling standards
    • Created new API rule documentation for timestamps, labels, bulk operations, and API stability markers

@tothandras tothandras requested a review from a team as a code owner April 15, 2026 14:09
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 15, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 412cda52-265e-4378-9eb5-7e3ddfe88877

📥 Commits

Reviewing files that changed from the base of the PR and between 171cbc2 and 075687a.

⛔ Files ignored due to path filters (1)
  • api/v3/openapi.yaml is excluded by !**/openapi.yaml
📒 Files selected for processing (60)
  • .agents/skills/api-filters/SKILL.md
  • .agents/skills/api/AIP.md
  • .agents/skills/api/SKILL.md
  • .agents/skills/api/rules/aip-122-naming.md
  • .agents/skills/api/rules/aip-126-enums.md
  • .agents/skills/api/rules/aip-129-labels.md
  • .agents/skills/api/rules/aip-132-list.md
  • .agents/skills/api/rules/aip-134-135-crud.md
  • .agents/skills/api/rules/aip-137-content-type.md
  • .agents/skills/api/rules/aip-142-time.md
  • .agents/skills/api/rules/aip-158-pagination.md
  • .agents/skills/api/rules/aip-160-filtering.md
  • .agents/skills/api/rules/aip-181-stability.md
  • .agents/skills/api/rules/aip-193-errors.md
  • .agents/skills/api/rules/aip-235-bulk-delete.md
  • .agents/skills/api/rules/aip-3101-versioning.md
  • .agents/skills/api/rules/aip-3106-empty-fields.md
  • .agents/skills/api/rules/aip-composition.md
  • .agents/skills/api/rules/aip-docs.md
  • .agents/skills/api/rules/aip-visibility.md
  • .gitignore
  • Makefile
  • api/spec/Makefile
  • api/spec/README.md
  • api/spec/packages/aip/README.md
  • api/spec/packages/aip/common/definitions/aip_filters.yaml
  • api/spec/packages/aip/common/definitions/errors.yaml
  • api/spec/packages/aip/common/definitions/konnect_properties.yaml
  • api/spec/packages/aip/common/definitions/metadatas.yaml
  • api/spec/packages/aip/common/definitions/properties.yaml
  • api/spec/packages/aip/common/definitions/security.yaml
  • api/spec/packages/aip/src/common/parameters.tsp
  • api/spec/packages/aip/src/customers/operations.tsp
  • api/spec/packages/aip/src/llmcost/operations.tsp
  • api/v3/api.gen.go
  • api/v3/codegen.yaml
  • api/v3/filters/convert.go
  • api/v3/filters/convert_test.go
  • api/v3/filters/filter.go
  • api/v3/filters/filter_test.go
  • api/v3/filters/parse.go
  • api/v3/filters/parse_test.go
  • api/v3/handlers/customers/list.go
  • api/v3/handlers/llmcost/convert.go
  • api/v3/handlers/llmcost/convert_test.go
  • api/v3/handlers/llmcost/list_overrides.go
  • api/v3/handlers/llmcost/list_prices.go
  • api/v3/templates/chi-middleware.tmpl.patch
  • openmeter/apiconverter/filter.go
  • openmeter/customer/adapter/customer.go
  • openmeter/customer/customer.go
  • openmeter/customer/httpdriver/customer.go
  • openmeter/ent/schema/customer.go
  • openmeter/llmcost/adapter/price.go
  • openmeter/llmcost/service.go
  • openmeter/llmcost/service/service.go
  • openmeter/llmcost/service/service_test.go
  • pkg/filter/filter.go
  • pkg/filter/filter_test.go
  • test/customer/customer.go

📝 Walkthrough

Walkthrough

This PR implements Kong AIP-160-style deepObject query-parameter filtering for OpenMeter v3 list endpoints. It adds comprehensive documentation, new filter type definitions, parsing and conversion logic, updates TypeSpec specifications, and refactors handlers/adapters to integrate the new filtering system across the API surface.

Changes

Cohort / File(s) Summary
API Documentation & Rules
.agents/skills/api-filters/SKILL.md, .agents/skills/api/SKILL.md, .agents/skills/api/AIP.md, .agents/skills/api/rules/aip-*.md (15 new rule files)
Added comprehensive AIP standard documentation covering naming (AIP-122), enums (AIP-126), labels (AIP-129), list endpoints (AIP-132), CRUD operations (AIP-134/135), content-type (AIP-137), time/duration (AIP-142), pagination (AIP-158), filtering (AIP-160), stability markers (AIP-181), error responses (AIP-193), bulk delete (AIP-235), versioning (AIP-3101), empty fields (AIP-3106), composition guidance, documentation requirements, and field visibility. Replaced monolithic api/spec/packages/aip/README.md with distributed rule files.
OpenAPI Schema Definitions
api/spec/packages/aip/common/definitions/aip_filters.yaml, api/spec/packages/aip/common/definitions/errors.yaml, api/spec/packages/aip/common/definitions/konnect_properties.yaml, api/spec/packages/aip/common/definitions/metadatas.yaml, api/spec/packages/aip/common/definitions/properties.yaml, api/spec/packages/aip/common/definitions/security.yaml
Fixed datetime filter operator semantics (DateTimeFieldGTFilter/GTEFilter), added PayloadTooLarge error response, introduced nullable UUID and label-update schemas, added pagination-related definitions, extended security schemes (portal/service/client tokens), and added role-specific ID schemas.
TypeSpec Filter Definitions
api/spec/packages/aip/src/common/parameters.tsp
Converted filter type placeholders from empty models to fully-defined structures: SortQuery to scalar, BooleanFieldFilter to scalar, NumericFieldFilter/StringFieldFilter/StringFieldFilterExact/DateTimeFieldFilter/LabelsFieldFilter to models/unions with explicit operators, documentation, and JSON tag encoding.
TypeSpec Operation Changes
api/spec/packages/aip/src/customers/operations.tsp, api/spec/packages/aip/src/llmcost/operations.tsp
Updated customer list filters (key from ExternalResourceKey to StringFieldFilter, added name/primary_email string filters). Updated LLM cost list filters to use StringFieldFilter instead of local FilterSingleString type.
API Spec Configuration & README
api/spec/Makefile, api/spec/README.md, api/v3/codegen.yaml, .gitignore
Added YAML post-processing to replace filter schema refs, wired custom chi-middleware template in codegen, updated spec README, and added template patch to gitignore.
Makefile Build Targets
Makefile
Added patch-oapi-templates target to download oapi-codegen, copy/patch chi-middleware template, and wired it as dependency for update-openapi and generate targets for filter-aware query parameter binding.
Core Filter Implementation
api/v3/filters/filter.go, api/v3/filters/filter_test.go
Replaced single StringFilter type with comprehensive typed filter structs: FilterBoolean, FilterNumeric, FilterDateTime, FilterString, FilterStringExact, each with appropriate operators (equality, ranges, set operations, existence checks). Removed old validation methods.
Filter Parsing & Conversion
api/v3/filters/parse.go, api/v3/filters/parse_test.go, api/v3/filters/convert.go, api/v3/filters/convert_test.go, api/v3/templates/chi-middleware.tmpl.patch
Implemented comprehensive URL query parsing via reflection, deep-object operator dispatch, value bounds/limits, and error collection. Added API-to-internal filter conversions with RFC-3339 datetime parsing and operator mapping. Extended chi-middleware template to parse filter[...] parameters via filters.Parse with proper error handling.
Handler Filter Processing
api/v3/handlers/customers/list.go, api/v3/handlers/llmcost/list_overrides.go, api/v3/handlers/llmcost/list_prices.go, api/v3/handlers/llmcost/convert.go, api/v3/handlers/llmcost/convert_test.go
Updated list handlers to parse/convert multiple typed filters and return standardized BadRequestError with InvalidParameters metadata on validation failures. Removed local FilterSingleString converter and updated test fixtures.
Service Layer Filter Updates
openmeter/customer/customer.go, openmeter/customer/httpdriver/customer.go, openmeter/llmcost/service.go, openmeter/llmcost/service/service.go, openmeter/llmcost/service/service_test.go
Switched from *string to *filter.FilterString for customer/llmcost list input filters. Added validation and conversion logic (includes new containsFilter helper for HTTP driver). Updated test fixtures.
Adapter & Ent Wiring
openmeter/customer/adapter/customer.go, openmeter/llmcost/adapter/price.go, openmeter/ent/schema/customer.go, openmeter/apiconverter/filter.go
Updated adapters to use filter.Select() method for Ent query building instead of explicit predicate functions. Added goverter ignore directives for operator mismatches. Added TODO documentation for query performance optimization.
Core Filter Package
pkg/filter/filter.go, pkg/filter/filter_test.go
Extended Filter interface with Select(field string) method for Ent integration. Added new operators (Contains/Ncontains). Refactored validation using shared sentinel errors and complexity checking. Added reflection-based IsEmpty() helper and Ent-specific LIKE predicate construction.
Test Coverage
test/customer/customer.go
Enhanced customer list tests with structured filter predicates covering operators (Ne, Ncontains, In, Exists, And compositions) and multiple filter scenarios.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler as HTTP Handler
    participant Parser as filters.Parse
    participant Converter as Converter<br/>(FromAPIFilter*)
    participant Adapter as Adapter
    participant Ent as Ent ORM

    Client->>Handler: GET /api/v3/customers?filter[name][contains]=acme<br/>filter[labels][eq]=env:prod
    Handler->>Parser: Parse(url.Values, &params.Filter)
    Parser->>Parser: Extract filter[name], filter[labels]<br/>from deepObject query keys
    Parser->>Parser: Dispatch by type: StringFieldFilter
    Parser->>Handler: params.Filter populated
    
    Handler->>Converter: FromAPIFilterString(params.Filter.Name)
    Converter->>Converter: Map API operators<br/>(Contains → Contains)
    Converter->>Handler: *filter.FilterString
    
    Handler->>Converter: FromAPIFilterString(params.Filter.Labels)
    Converter->>Handler: *filter.FilterString
    
    Handler->>Adapter: ListCustomers(ctx, req)
    Adapter->>Ent: input.Name.Select("name")
    Ent->>Ent: Returns func(*sql.Selector)<br/>with ILIKE predicate
    Adapter->>Ent: Apply selector to query
    Adapter->>Ent: Build WHERE clauses<br/>for all filters
    
    Ent->>Ent: Execute SQL query
    Ent->>Adapter: Customer records
    Adapter->>Handler: ListCustomersResponse
    Handler->>Client: 200 OK + filtered results
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • feat(api): add meter query v3 handler #3927 — Concurrent modifications to pkg/filter types and API→internal filter selection/conversion logic in the filtering domain.
  • feat: support AIP filtering #4117 — Duplicate PR covering identical changes: api/v3/filters implementation, pkg/filter extensions, chi-middleware wiring, TypeSpec updates, and handler/adapter refactoring.
  • chore: add AIP skills #4134 — Parallel documentation additions for API filtering skills and AIP-160 rules with the same deepObject filter workflow specification.

Suggested labels

release-note/feature

Suggested reviewers

  • turip
  • chrisgacsal
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/api-v3-filters-no-reflect

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@tothandras tothandras closed this Apr 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant