From b1d05c7e66553601398bd330487116bc0bb0958a Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Wed, 3 Dec 2025 17:58:58 -0500 Subject: [PATCH] A quick version update for the god like catch all CRUD endpoints. Version 3 will be even better! --- GEMINI.md | 8 +++ app/main.py | 4 +- documentation/API_SIMPLIFICATION_PLAN.md | 53 +++++++++++++++++++ .../JOURNALS_API_MIGRATION.md | 0 .../REWRITE_PLAN.md | 0 .../REWRITE_PLAN_V2.md | 0 6 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 documentation/API_SIMPLIFICATION_PLAN.md rename JOURNALS_API_MIGRATION.md => documentation/JOURNALS_API_MIGRATION.md (100%) rename REWRITE_PLAN.md => documentation/REWRITE_PLAN.md (100%) rename REWRITE_PLAN_V2.md => documentation/REWRITE_PLAN_V2.md (100%) diff --git a/GEMINI.md b/GEMINI.md index cdb9918..626be8a 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,5 +1,13 @@ # Gemini Added Memories +## Learnings from session (December 3, 2025): + +* **File Location:** The `GEMINI.md` file must always be located in the project root directory. +* **V2 CRUD Endpoint:** API simplification will be centered around the generic `/v2/crud` endpoint defined in `app/routers/api_crud_v2.py`. This is the modern, preferred implementation over the v1 endpoint in `api_crud.py`. +* **Data-Driven Configuration:** The v2 endpoint is highly modular and configured via the `obj_type_kv_li` dictionary in `app/ae_obj_types_def.py`. This dictionary acts as a central registry, mapping URL object strings to their corresponding database tables, Pydantic models, and export configurations. New simple CRUD objects can be added just by updating this dictionary. +* **Complex Filtering with `jp`:** The generic list handler (`handle_get_obj_li`) supports advanced filtering. While it has basic support for foreign key lookups via `for_obj_type` and `for_obj_id` parameters, more complex queries, such as those involving polymorphic relationships (e.g., filtering `journal` by a `user` using `for_type` and `for_id` columns), must be handled by the client. The client should construct and send a custom query using the powerful `jp` (JSON payload) query parameter. +* **Migration Plan Focus:** The user prefers to remain in a planning and documentation phase. The immediate goal is to update the `API_SIMPLIFICATION_PLAN.md` with detailed migration steps, rather than executing code changes directly. + ## Learnings from previous session (December 2, 2025): * **Docker Environment Challenges:** Debugging issues in a Dockerized FastAPI environment when running locally (outside the container's execution context) is significantly more challenging due to environment mismatches and symlinked executables. Direct `uvicorn` execution for debugging is not viable in this setup. This necessitates an approach that can either: diff --git a/app/main.py b/app/main.py index 345bfeb..ff93ed7 100644 --- a/app/main.py +++ b/app/main.py @@ -100,7 +100,7 @@ app.include_router( app.include_router( api_crud.router, prefix='/crud', - tags=['CRUD v1.1 (Legacy)'], + tags=['CRUD v1.2 (Legacy)'], #dependencies=[Depends(get_token_header)], #dependencies=[Depends(get_account_header)], #responses={404: {'description': 'Not found'}}, @@ -108,7 +108,7 @@ app.include_router( app.include_router( api_crud_v2.router, prefix='/v2/crud', - tags=['CRUD v2.1'], + tags=['CRUD v2.5'], #dependencies=[Depends(get_token_header)], #dependencies=[Depends(get_account_header)], #responses={404: {'description': 'Not found'}}, diff --git a/documentation/API_SIMPLIFICATION_PLAN.md b/documentation/API_SIMPLIFICATION_PLAN.md new file mode 100644 index 0000000..306d44a --- /dev/null +++ b/documentation/API_SIMPLIFICATION_PLAN.md @@ -0,0 +1,53 @@ +# Aether API V3 Implementation Plan + +This document outlines the plan to build the Aether API V3. The goal of V3 is to create a new, modern, and consistent set of API endpoints that will run in parallel with the existing legacy endpoints. No existing endpoints will be modified or deleted. + +## V3 Architecture + +The V3 API will be centered around a new generic CRUD router that implements a hierarchical, nested URL structure for parent-child object relationships. + +- **Endpoint Prefix:** All new endpoints will be under `/v3/crud/`. +- **Top-Level Objects:** Handled via a flat URL structure. + - `GET /v3/crud/journal/` + - `POST /v3/crud/journal/` + - `GET /v3/crud/journal/{journal_id}` +- **Child Objects:** Handled via a nested URL structure that enforces the parent-child relationship. + - `GET /v3/crud/journal/{journal_id}/journal_entry/` + - `POST /v3/crud/journal/{journal_id}/journal_entry/` + - `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` + +This structure will be implemented in a new `app/routers/api_crud_v3.py` file, which will be inspired by the logic in the existing `api_crud_v2.py` but with updated routing to handle the nesting. + +## Implementation Phases + +### Phase 1: Create Stub V3 Endpoint (Proof-of-Concept) + +The first step is to create a minimal, non-functional "stub" endpoint to prove that the basic routing and application integration works. + +1. **Create File:** Create a new file: `app/routers/api_crud_v3.py`. +2. **Add Stub Endpoint:** Add a simple health-check or "hello world" endpoint within this file, for example, a `GET` endpoint at `/v3/crud/health`. +3. **Update Main App:** In `app/main.py`, import and include the new V3 router. + +### Phase 2: Implement Top-Level Object CRUD + +Using `journal` as the first test case, implement the full set of CRUD operations for a top-level object. + +- `GET /v3/crud/journal/` +- `POST /v3/crud/journal/` +- `GET /v3/crud/journal/{journal_id}` +- `PATCH /v3/crud/journal/{journal_id}` +- `DELETE /v3/crud/journal/{journal_id}` + +### Phase 3: Implement Nested Object CRUD + +Using `journal_entry` as the first test case, implement the full set of CRUD operations for a child object, ensuring the `journal_id` from the URL is used for filtering. + +- `GET /v3/crud/journal/{journal_id}/journal_entry/` +- `POST /v3/crud/journal/{journal_id}/journal_entry/` +- `GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` +- `PATCH /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` +- `DELETE /v3/crud/journal/{journal_id}/journal_entry/{entry_id}` + +### Phase 4: Incremental Rollout + +Once the patterns for top-level and nested objects are proven with Journal and Journal Entry, we will apply the same pattern to other Aether objects in batches. \ No newline at end of file diff --git a/JOURNALS_API_MIGRATION.md b/documentation/JOURNALS_API_MIGRATION.md similarity index 100% rename from JOURNALS_API_MIGRATION.md rename to documentation/JOURNALS_API_MIGRATION.md diff --git a/REWRITE_PLAN.md b/documentation/REWRITE_PLAN.md similarity index 100% rename from REWRITE_PLAN.md rename to documentation/REWRITE_PLAN.md diff --git a/REWRITE_PLAN_V2.md b/documentation/REWRITE_PLAN_V2.md similarity index 100% rename from REWRITE_PLAN_V2.md rename to documentation/REWRITE_PLAN_V2.md