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

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.