OSIT-AE-API-FastAPI/documentation/Aether_API_CRUD_V3_beta_recommendations.md

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