32 lines
2.2 KiB
Markdown
32 lines
2.2 KiB
Markdown
# Aether API CRUD V3 Beta Recommendations
|
|
|
|
Following the initial migration of the Journals module to the V3 CRUD endpoints, the following architectural recommendations are proposed for the FastAPI backend to improve developer experience and frontend efficiency.
|
|
|
|
---
|
|
|
|
## 1. "View" Selection (`use_alt_tbl` Replacement)
|
|
In V2, the `use_alt_tbl` flag was frequently used to fetch "rich" objects (e.g., including joined data like `person_name`).
|
|
- **Recommendation:** Implement a `response_view` (or `view`) query parameter for both GET list and POST search endpoints.
|
|
- **Example:** `GET /v3/crud/journal/?view=enriched`
|
|
- **Goal:** Allow the client to request a heavier model with joined fields only when necessary, keeping the default response lightweight.
|
|
|
|
## 2. Hybrid Filtering for Search
|
|
Currently, the `/search` endpoint requires a full JSON body even for simple standard filters like `enabled` or `hidden`.
|
|
- **Recommendation:** Update the `POST .../search` endpoint to accept standard query parameters that automatically append `AND` conditions to the logic defined in the body.
|
|
- **Example:** `POST /v3/crud/journal/search?enabled=true`
|
|
- **Goal:** Simplifies frontend code for common toggles while still allowing complex logic in the POST body.
|
|
|
|
## 3. Standardized Full-Text Search Field
|
|
The current migration uses a field named `default_qry_str` with a `match` operator for text search.
|
|
- **Recommendation:** Implement a reserved top-level property in the Search Pydantic model (e.g., `_search_` or `query_string`) specifically for global text search.
|
|
- **Goal:** Decouples the frontend from knowing specific database column names used for full-text indexing. The backend can then decide which columns (name, description, tags, etc.) to include in the search.
|
|
|
|
## 4. Explicit "Parent" Filtering in Search
|
|
Filtering by parent (e.g., Account or Site) is a primary use case but currently requires manual injection into the `and` array.
|
|
- **Recommendation:** Expose `for_obj_type` and `for_obj_id` as top-level arguments in the Search API.
|
|
- **Goal:** Standardizes how parent context is passed, allowing the backend to more easily perform ownership and permission validation before executing the search.
|
|
|
|
---
|
|
**Date:** 2026-01-02
|
|
**Status:** Beta Feedback
|