Aether API V3 Frontend Integration Guide (Svelte/TypeScript)

This guide explains how to update or create frontend functions to interact with the new Aether API V3 CRUD endpoints. V3 introduces a nested URL structure, a powerful POST-based search, and improved performance.

1. Key Differences (V2 vs V3)

Feature	CRUD V2 (Legacy)	CRUD V3 (Modern)
Base Prefix	`/v2/crud`	`/v3/crud`
List Suffix	Uses `/list`	No suffix (e.g., `/v3/crud/journal/`)
Nested Path	Not supported in URL	Supported (e.g., `/v3/crud/journal/{id}/journal_entry/`)
View Selection	`tbl_alt`, `mdl_alt`	`view` parameter (e.g., `?view=enriched`)
Complex Search	Limited to GET `jp`	POST `/search` (Unlimited size + Hybrid params)
Full-Text Search	Manual column names	Reserved `q` property in SearchQuery

2. Implementing V3 CRUD Functions

A. List & Single Object (GET)

Support for view selection allows fetching richer data models when needed.

// Example: Get enriched journal details
// GET /v3/crud/journal/{id}?view=enriched
export async function get_ae_obj_v3({ api_cfg, obj_type, obj_id, view = 'default' }) {
    const endpoint = `/v3/crud/${obj_type}/${obj_id}`;
    return await get_object({ api_cfg, endpoint, params: { view } });
}

B. Advanced & Hybrid Search (POST)

The /search endpoint combines the power of complex logical bodies with the simplicity of query parameters.

export async function search_ae_obj_v3({
    api_cfg,
    obj_type,
    search_query, // { q: "search term", and: [...] }
    enabled = 'enabled',
    view = 'default',
    for_obj_type,
    for_obj_id
}) {
    const endpoint = `/v3/crud/${obj_type}/search`;
    
    // Standard filters can be passed as query params
    const params: any = { enabled, view };
    if (for_obj_type) params.for_obj_type = for_obj_type;
    if (for_obj_id) params.for_obj_id = for_obj_id;

    return await post_object({ 
        api_cfg, 
        endpoint, 
        params, 
        data: search_query 
    });
}

C. Standardized Global Search

Use the q property in your search body for a general keyword search across indexed columns.

// POST /v3/crud/journal/search
{
  "q": "Annual Meeting",
  "and": [
    { "field": "enable", "op": "eq", "value": true }
  ]
}

3. Best Practices for V3

Use view for Rich Data: Instead of manually joining data in separate calls, use ?view=enriched or ?view=detail if defined in the backend.
Hybrid Search: Use query parameters for simple toggles (enabled/hidden) and the POST body for complex logic.
Global Search: Always prefer the q property for text search instead of manually targeting default_qry_str.
Singular Nouns: Always use singular names for obj_type (e.g., journal).

2.8 KiB Raw Blame History