53 lines
2.7 KiB
Markdown
53 lines
2.7 KiB
Markdown
# 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. |