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.

Create File: Create a new file: app/routers/api_crud_v3.py.
Add Stub Endpoint: Add a simple health-check or "hello world" endpoint within this file, for example, a GET endpoint at /v3/crud/health.
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.

2.7 KiB Raw Blame History