87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# Journals API Migration Plan
|
|
|
|
This document outlines the plan for migrating the Journals API to the new, standardized Aether API architecture.
|
|
|
|
## 1. Current API Analysis
|
|
|
|
The Journals module consists of two main objects: `journal` and `journal_entry`. Currently, these objects are primarily accessed through the generic CRUD endpoints.
|
|
|
|
### How the Front-End Likely Interacts with the API:
|
|
|
|
* **Create a Journal:**
|
|
* `POST /v2/crud/journal`
|
|
* **Body:** A JSON object with all the fields from the `Journal_Base` model.
|
|
|
|
* **Get a Journal:**
|
|
* `GET /v2/crud/journal/{journal_id_random}`
|
|
|
|
* **List Journals:**
|
|
* `GET /v2/crud/journal/list`
|
|
* This would also likely use the `for_obj_type` and `for_obj_id` query parameters to get journals for a specific person or account (e.g., `GET /v2/crud/journal/list?for_obj_type=person&for_obj_id={person_id_random}`).
|
|
|
|
* **Update a Journal:**
|
|
* `PATCH /v2/crud/journal/{journal_id_random}`
|
|
* **Body:** A JSON object with the fields to be updated.
|
|
|
|
* **Delete a Journal:**
|
|
* `DELETE /v2/crud/journal/{journal_id_random}`
|
|
|
|
The same patterns apply to the `journal_entry` object.
|
|
|
|
## 2. Proposed New API
|
|
|
|
The new Journals API will be more explicit, organized, and easier to use. It will follow the new architectural principles of the Aether API rewrite.
|
|
|
|
### New URL Structure:
|
|
|
|
* `/journals/`
|
|
* `/journals/{journal_id_random}`
|
|
* `/journals/{journal_id_random}/entries/`
|
|
* `/journals/{journal_id_random}/entries/{entry_id_random}`
|
|
|
|
### New Models:
|
|
|
|
We will create new, simplified models for `Journal` and `JournalEntry` that inherit from the `CoreObject` base model.
|
|
|
|
* `app/models/journal.py`:
|
|
* `JournalBase(CoreObject)`
|
|
* `Journal(JournalBase)`
|
|
* `JournalInDB(Journal, CoreObjectInDB)`
|
|
* `JournalCreate(JournalBase)`
|
|
* `JournalUpdate(JournalBase)`
|
|
* `app/models/journal_entry.py`:
|
|
* `JournalEntryBase(CoreObject)`
|
|
* `JournalEntry(JournalEntryBase)`
|
|
* `JournalEntryInDB(JournalEntry, CoreObjectInDB)`
|
|
* `JournalEntryCreate(JournalEntryBase)`
|
|
* `JournalEntryUpdate(JournalEntryBase)`
|
|
|
|
### New Endpoints:
|
|
|
|
A new `app/routers/journals.py` router will be created with the following explicit endpoints:
|
|
|
|
* `POST /journals/`: Create a new journal.
|
|
* `GET /journals/`: List all journals (with query params for filtering).
|
|
* `GET /journals/{journal_id_random}`: Get a single journal by its `id_random`.
|
|
* `PATCH /journals/{journal_id_random}`: Update a journal.
|
|
* `DELETE /journals/{journal_id_random}`: Delete a journal.
|
|
* `POST /journals/{journal_id_random}/entries/`: Create a new journal entry for a specific journal.
|
|
* `GET /journals/{journal_id_random}/entries/`: List all entries for a specific journal.
|
|
* `GET /journals/{journal_id_random}/entries/{entry_id_random}`: Get a single journal entry.
|
|
* `PATCH /journals/{journal_id_random}/entries/{entry_id_random}`: Update a journal entry.
|
|
* `DELETE /journals/{journal_id_random}/entries/{entry_id_random}`: Delete a journal entry.
|
|
|
|
## 3. Side-by-Side Comparison
|
|
|
|
| Operation | Current API Call | Proposed New API Call |
|
|
| --- | --- | --- |
|
|
| Create Journal | `POST /v2/crud/journal` | `POST /journals/` |
|
|
| Get Journal | `GET /v2/crud/journal/{id}` | `GET /journals/{id}` |
|
|
| List Journals | `GET /v2/crud/journal/list` | `GET /journals/` |
|
|
| Update Journal | `PATCH /v2/crud/journal/{id}` | `PATCH /journals/{id}` |
|
|
| Delete Journal | `DELETE /v2/crud/journal/{id}` | `DELETE /journals/{id}` |
|
|
| Create Entry | `POST /v2/crud/journal_entry` (with `journal_id_random` in body) | `POST /journals/{journal_id}/entries/` |
|
|
| List Entries | `GET /v2/crud/journal_entry/list?for_obj_type=journal&for_obj_id={id}` | `GET /journals/{journal_id}/entries/` |
|
|
|
|
This plan provides a clear path forward for refactoring the Journals module. By following this plan, we can create a more maintainable and user-friendly API while ensuring a smooth transition for the front-end.
|