Added samples for Svelte side API code and a new CRUD V3 API guide.
This commit is contained in:
Scott Idem
297
documentation/Aether_Svelte_API_TS_code_samples.md
Normal file
297
documentation/Aether_Svelte_API_TS_code_samples.md
Normal file
@@ -0,0 +1,297 @@
|
|||||||
|
```ts
|
||||||
|
export async function get_ae_obj_id_crud({
|
||||||
|
api_cfg,
|
||||||
|
no_account_id = false,
|
||||||
|
obj_type,
|
||||||
|
obj_id,
|
||||||
|
use_alt_table = false,
|
||||||
|
use_alt_base = false,
|
||||||
|
inc = {},
|
||||||
|
enabled = 'enabled',
|
||||||
|
hidden = 'not_hidden',
|
||||||
|
limit = 999999,
|
||||||
|
offset = 0,
|
||||||
|
data = {},
|
||||||
|
// key,
|
||||||
|
// jwt = null,
|
||||||
|
headers = {},
|
||||||
|
params = {},
|
||||||
|
timeout = 25000,
|
||||||
|
return_meta = false,
|
||||||
|
log_lvl = 0
|
||||||
|
}: {
|
||||||
|
api_cfg: any;
|
||||||
|
no_account_id?: boolean;
|
||||||
|
obj_type: string;
|
||||||
|
obj_id: string;
|
||||||
|
use_alt_table?: boolean;
|
||||||
|
use_alt_base?: boolean;
|
||||||
|
inc?: any;
|
||||||
|
enabled?: 'enabled' | 'all' | 'not_enabled' | undefined;
|
||||||
|
hidden?: 'hidden' | 'all' | 'not_hidden' | undefined;
|
||||||
|
limit?: number;
|
||||||
|
offset?: number;
|
||||||
|
data?: any;
|
||||||
|
// key: string,
|
||||||
|
// jwt?: string,
|
||||||
|
headers?: any;
|
||||||
|
params?: key_val;
|
||||||
|
timeout?: number;
|
||||||
|
return_meta?: boolean;
|
||||||
|
log_lvl?: number;
|
||||||
|
}) {
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Updated 2024-05-23
|
||||||
|
export const patch_object = async function patch_object({
|
||||||
|
api_cfg = null,
|
||||||
|
endpoint = '',
|
||||||
|
params = {},
|
||||||
|
data = {},
|
||||||
|
return_meta = false,
|
||||||
|
log_lvl = 0,
|
||||||
|
retry_count = 5 // Number of retry attempts
|
||||||
|
}: {
|
||||||
|
api_cfg: any;
|
||||||
|
endpoint: string;
|
||||||
|
params?: any;
|
||||||
|
data?: any;
|
||||||
|
return_meta?: boolean;
|
||||||
|
log_lvl?: number;
|
||||||
|
retry_count?: number;
|
||||||
|
}) {
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Updated 2024-05-23
|
||||||
|
export const post_object = async function post_object({
|
||||||
|
api_cfg = null,
|
||||||
|
endpoint = '',
|
||||||
|
params = {},
|
||||||
|
data = {},
|
||||||
|
form_data = null,
|
||||||
|
return_meta = false,
|
||||||
|
return_blob = false,
|
||||||
|
filename = '',
|
||||||
|
auto_download = false,
|
||||||
|
// The task_id value should be a random string that is unique to the task. This is used to identify the task in the message event.
|
||||||
|
task_id = crypto.randomUUID(),
|
||||||
|
log_lvl = 0,
|
||||||
|
retry_count = 5
|
||||||
|
}: {
|
||||||
|
api_cfg: any;
|
||||||
|
endpoint: string;
|
||||||
|
params?: any;
|
||||||
|
data?: any;
|
||||||
|
form_data?: any;
|
||||||
|
return_meta?: boolean;
|
||||||
|
return_blob?: boolean;
|
||||||
|
filename?: string;
|
||||||
|
auto_download?: boolean;
|
||||||
|
task_id?: string;
|
||||||
|
log_lvl?: number;
|
||||||
|
retry_count?: number;
|
||||||
|
}) {
|
||||||
|
```
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Updated 2024-05-23
|
||||||
|
export const delete_object = async function delete_object({
|
||||||
|
api_cfg = null,
|
||||||
|
endpoint = '',
|
||||||
|
params = {},
|
||||||
|
data = {},
|
||||||
|
return_meta = false,
|
||||||
|
log_lvl = 0,
|
||||||
|
retry_count = 5 // Number of retry attempts
|
||||||
|
}: {
|
||||||
|
api_cfg: any;
|
||||||
|
endpoint: string;
|
||||||
|
params?: any;
|
||||||
|
data?: any;
|
||||||
|
return_meta?: boolean;
|
||||||
|
log_lvl?: number;
|
||||||
|
retry_count?: number;
|
||||||
|
}) {
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import type { key_val } from '$lib/stores/ae_stores';
|
||||||
|
import { get_object } from './api_get_object';
|
||||||
|
|
||||||
|
// Refactored 2025-11-13 to use a lookup map for endpoints.
|
||||||
|
const objTypeToEndpointMap: Record<string, string> = {
|
||||||
|
account: '/crud/account/list',
|
||||||
|
address: '/crud/address/list',
|
||||||
|
archive: '/crud/archive/list',
|
||||||
|
archive_content: '/crud/archive/content/list',
|
||||||
|
activity_log: '/crud/activity_log/list',
|
||||||
|
contact: '/crud/contact/list',
|
||||||
|
data_store: '/crud/data_store/list',
|
||||||
|
event: '/crud/event/list',
|
||||||
|
event_abstract: '/crud/event/abstract/list',
|
||||||
|
event_badge: '/crud/event/badge/list',
|
||||||
|
event_badge_template: '/crud/event/badge/template/list',
|
||||||
|
event_device: '/crud/event/device/list',
|
||||||
|
event_exhibit: '/crud/event/exhibit/list',
|
||||||
|
event_exhibit_tracking: '/crud/event/exhibit/tracking/list',
|
||||||
|
event_file: '/crud/event/file/list',
|
||||||
|
event_location: '/crud/event/location/list',
|
||||||
|
event_person: '/crud/event/person/list',
|
||||||
|
event_presentation: '/crud/event/presentation/list',
|
||||||
|
event_presenter: '/crud/event/presenter/list',
|
||||||
|
event_session: '/crud/event/session/list',
|
||||||
|
event_track: '/crud/event/track/list',
|
||||||
|
grant: '/crud/grant/list',
|
||||||
|
hosted_file: '/crud/hosted_file/list',
|
||||||
|
journal: '/crud/journal/list',
|
||||||
|
journal_entry: '/crud/journal/entry/list',
|
||||||
|
order: '/crud/order/list',
|
||||||
|
order_line: '/crud/order/line/list',
|
||||||
|
page: '/crud/page/list',
|
||||||
|
person: '/crud/person/list',
|
||||||
|
post: '/crud/post/list',
|
||||||
|
post_comment: '/crud/post/comment/list',
|
||||||
|
site: '/crud/site/list',
|
||||||
|
sponsorship_cfg: '/crud/sponsorship/cfg/list',
|
||||||
|
sponsorship: '/crud/sponsorship/list',
|
||||||
|
// user: '/crud/user/list',
|
||||||
|
'lu-country_subdivision': '/crud/lu/country_subdivision/list',
|
||||||
|
'lu-country': '/crud/lu/country/list',
|
||||||
|
'lu-time_zone': '/crud/lu/time_zone/list'
|
||||||
|
};
|
||||||
|
|
||||||
|
function getEndpointForObjType(obj_type: string, for_obj_type?: string): string {
|
||||||
|
if (obj_type === 'lu' && for_obj_type) {
|
||||||
|
const key = `lu-${for_obj_type}`;
|
||||||
|
const endpoint = objTypeToEndpointMap[key];
|
||||||
|
if (endpoint) return endpoint;
|
||||||
|
}
|
||||||
|
|
||||||
|
const endpoint = objTypeToEndpointMap[obj_type];
|
||||||
|
if (endpoint) return endpoint;
|
||||||
|
|
||||||
|
throw new Error(`Unknown object type: ${obj_type}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
type OrderBy = { [key: string]: 'ASC' | 'DESC' };
|
||||||
|
|
||||||
|
interface GetAeObjLiForObjIdCrudV2Params {
|
||||||
|
api_cfg: any; // Consider defining a specific type for api_cfg
|
||||||
|
obj_type: string;
|
||||||
|
for_obj_type: string;
|
||||||
|
for_obj_id?: string;
|
||||||
|
use_alt_tbl?: boolean | string;
|
||||||
|
use_alt_mdl?: boolean | string;
|
||||||
|
use_alt_exp?: boolean | string;
|
||||||
|
inc?: key_val;
|
||||||
|
enabled?: 'all' | 'enabled' | 'not_enabled';
|
||||||
|
hidden?: 'all' | 'hidden' | 'not_hidden';
|
||||||
|
order_by_li?: OrderBy[] | null;
|
||||||
|
limit?: number;
|
||||||
|
offset?: number;
|
||||||
|
headers?: Record<string, string>;
|
||||||
|
params_json?: any;
|
||||||
|
params?: key_val;
|
||||||
|
log_lvl?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function get_ae_obj_li_for_obj_id_crud_v2({
|
||||||
|
api_cfg,
|
||||||
|
obj_type,
|
||||||
|
for_obj_type,
|
||||||
|
for_obj_id,
|
||||||
|
use_alt_tbl = false,
|
||||||
|
use_alt_mdl = false,
|
||||||
|
use_alt_exp = false,
|
||||||
|
enabled = 'enabled',
|
||||||
|
hidden = 'not_hidden',
|
||||||
|
order_by_li = null,
|
||||||
|
limit = 999999,
|
||||||
|
offset = 0,
|
||||||
|
headers = {},
|
||||||
|
params_json = null,
|
||||||
|
params = {},
|
||||||
|
log_lvl = 0
|
||||||
|
}: GetAeObjLiForObjIdCrudV2Params) {
|
||||||
|
if (log_lvl) {
|
||||||
|
console.log('*** get_ae_obj_li_for_obj_id_crud_v2() ***');
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
const endpoint = `/v2${getEndpointForObjType(obj_type, for_obj_type)}`;
|
||||||
|
if (log_lvl) {
|
||||||
|
console.log('Endpoint:', endpoint);
|
||||||
|
}
|
||||||
|
|
||||||
|
// We need to remove a few parameters from the params object that are not allowed.
|
||||||
|
delete params['qry__enabled'];
|
||||||
|
delete params['qry__hidden'];
|
||||||
|
delete params['qry__limit'];
|
||||||
|
delete params['qry__offset'];
|
||||||
|
|
||||||
|
if (for_obj_type) params['for_obj_type'] = for_obj_type;
|
||||||
|
if (for_obj_id) params['for_obj_id'] = for_obj_id;
|
||||||
|
|
||||||
|
if (use_alt_tbl === true) params['tbl_alt'] = 'alt';
|
||||||
|
if (use_alt_mdl === true) params['mdl_alt'] = 'alt';
|
||||||
|
if (use_alt_exp === true) params['exp_alt'] = 'alt';
|
||||||
|
|
||||||
|
const allowed_enabled_list = ['all', 'enabled', 'not_enabled'];
|
||||||
|
if (allowed_enabled_list.includes(enabled)) {
|
||||||
|
params['enabled'] = enabled;
|
||||||
|
}
|
||||||
|
|
||||||
|
const allowed_hidden_list = ['all', 'hidden', 'not_hidden'];
|
||||||
|
if (allowed_hidden_list.includes(hidden)) {
|
||||||
|
params['hidden'] = hidden;
|
||||||
|
}
|
||||||
|
|
||||||
|
// NOTE: The order_by_li variable is in the "headers" because URL GET params do not handle complex objects very well.
|
||||||
|
if (order_by_li) {
|
||||||
|
headers['order_by_li'] = JSON.stringify(order_by_li);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (limit > 0) params['limit'] = limit;
|
||||||
|
if (offset > 0) params['offset'] = offset;
|
||||||
|
|
||||||
|
if (params_json) {
|
||||||
|
// NOTE: "jp" stands for "JSON Params". This is a JSON object that needs to be safely converted to a string for the params.
|
||||||
|
// Max characters for a GET request is ~2000. This is a limitation of the browser.
|
||||||
|
const json_params_str = encodeURIComponent(JSON.stringify(params_json));
|
||||||
|
if (json_params_str.length > 2083) {
|
||||||
|
// Using console.error instead of throwing an error to avoid crashing the app for a known limitation.
|
||||||
|
console.error(
|
||||||
|
`The JSON object is too large to be used as a GET parameter. Max length is 2083 characters. Length = ${json_params_str.length}`
|
||||||
|
);
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
params['jp'] = json_params_str;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (log_lvl) {
|
||||||
|
console.log('Params:', params);
|
||||||
|
}
|
||||||
|
|
||||||
|
const object_li_get_promise = await get_object({
|
||||||
|
api_cfg: api_cfg,
|
||||||
|
endpoint: endpoint,
|
||||||
|
headers: headers,
|
||||||
|
params: params,
|
||||||
|
log_lvl: log_lvl
|
||||||
|
});
|
||||||
|
|
||||||
|
if (log_lvl > 1) {
|
||||||
|
console.log(object_li_get_promise);
|
||||||
|
}
|
||||||
|
|
||||||
|
return object_li_get_promise;
|
||||||
|
} catch (error) {
|
||||||
|
console.error('Error in get_ae_obj_li_for_obj_id_crud_v2:', error);
|
||||||
|
return false; // Or handle the error as appropriate
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
131
documentation/V3_FRONTEND_API_GUIDE.md
Normal file
131
documentation/V3_FRONTEND_API_GUIDE.md
Normal file
@@ -0,0 +1,131 @@
|
|||||||
|
# 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` (e.g., `/v2/crud/journal/list`) | **No suffix** (e.g., `/v3/crud/journal/`) |
|
||||||
|
| **Nested Path** | Not supported in URL path | **Supported** (e.g., `/v3/crud/journal/{id}/journal_entry/`) |
|
||||||
|
| **Order By** | Passed in **Headers** (`order_by_li`) | Passed as **Query Parameter** (`order_by_li`) |
|
||||||
|
| **Complex Search**| Limited to GET `jp` (~2KB limit) | **POST `/search`** (Unlimited size) |
|
||||||
|
| **Latency Simulation**| Not standardized | `X-Delay-ms` (Header) or `delay_ms` (Query) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Implementing V3 CRUD Functions
|
||||||
|
|
||||||
|
### A. List Top-Level Objects (GET)
|
||||||
|
Use this for simple lists or filtering by a parent via query parameters.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
export async function get_ae_obj_li_v3({
|
||||||
|
api_cfg,
|
||||||
|
obj_type,
|
||||||
|
for_obj_type,
|
||||||
|
for_obj_id,
|
||||||
|
enabled = 'enabled',
|
||||||
|
hidden = 'not_hidden',
|
||||||
|
limit = 100,
|
||||||
|
offset = 0,
|
||||||
|
order_by_li = null, // e.g., {"created_on": "DESC"}
|
||||||
|
delay_ms = 0
|
||||||
|
}) {
|
||||||
|
// 1. Build V3 Endpoint (Note: No /list suffix)
|
||||||
|
const endpoint = `/v3/crud/${obj_type}/`;
|
||||||
|
|
||||||
|
// 2. Build Query Params
|
||||||
|
const params: any = {
|
||||||
|
enabled,
|
||||||
|
hidden,
|
||||||
|
limit,
|
||||||
|
offset
|
||||||
|
};
|
||||||
|
|
||||||
|
if (for_obj_type) params.for_obj_type = for_obj_type;
|
||||||
|
if (for_obj_id) params.for_obj_id = for_obj_id;
|
||||||
|
if (order_by_li) params.order_by_li = JSON.stringify(order_by_li);
|
||||||
|
if (delay_ms) params.delay_ms = delay_ms;
|
||||||
|
|
||||||
|
return await get_object({ api_cfg, endpoint, params });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### B. Access Nested Objects (GET)
|
||||||
|
V3 allows you to enforce parent-child relationships directly in the URL.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// Example: Get all entries for a specific journal
|
||||||
|
// GET /v3/crud/journal/{journal_id}/journal_entry/
|
||||||
|
export async function get_nested_obj_li_v3({
|
||||||
|
api_cfg,
|
||||||
|
parent_type,
|
||||||
|
parent_id,
|
||||||
|
child_type,
|
||||||
|
limit = 100
|
||||||
|
}) {
|
||||||
|
const endpoint = `/v3/crud/${parent_type}/${parent_id}/${child_type}/`;
|
||||||
|
return await get_object({ api_cfg, endpoint, params: { limit } });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### C. Advanced Search (POST)
|
||||||
|
Use the new `/search` endpoint for complex logic (AND/OR, LIKE, IN) that would exceed URL length limits.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
export async function search_ae_obj_v3({
|
||||||
|
api_cfg,
|
||||||
|
obj_type,
|
||||||
|
search_query, // Complex SearchQuery object
|
||||||
|
order_by_li = null
|
||||||
|
}) {
|
||||||
|
const endpoint = `/v3/crud/${obj_type}/search`;
|
||||||
|
|
||||||
|
const params: any = {};
|
||||||
|
if (order_by_li) params.order_by_li = JSON.stringify(order_by_li);
|
||||||
|
|
||||||
|
// Note: search_query is sent in the BODY via POST
|
||||||
|
return await post_object({
|
||||||
|
api_cfg,
|
||||||
|
endpoint,
|
||||||
|
params,
|
||||||
|
data: search_query
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Example search_query usage:
|
||||||
|
* {
|
||||||
|
* "and": [
|
||||||
|
* { "field": "enable", "op": "eq", "value": true },
|
||||||
|
* {
|
||||||
|
* "or": [
|
||||||
|
* { "field": "name", "op": "like", "value": "%Meeting%" },
|
||||||
|
* { "field": "priority", "op": "gt", "value": 5 }
|
||||||
|
* ]
|
||||||
|
* }
|
||||||
|
* ]
|
||||||
|
* }
|
||||||
|
*/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Best Practices for V3
|
||||||
|
|
||||||
|
1. **Stop using Headers for Sorting**: In V2, we used `headers['order_by_li']`. In V3, always use `params['order_by_li']`.
|
||||||
|
2. **Prefer `/search` for Filters**: If your query involves more than a simple `for_obj_id`, use the `POST .../search` endpoint. It is safer, more readable, and bypasses the 2083-character URL limit.
|
||||||
|
3. **Non-Blocking UI**: Use the `delay_ms` parameter during development to test how your Svelte components handle loading states and skeleton screens.
|
||||||
|
4. **Singular Nouns**: Always use singular names for `obj_type` (e.g., `journal`, not `journals`), following the backend's `obj_type_kv_li` registry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Special Case: Account Context
|
||||||
|
V3 strictly enforces account context. Ensure your `api_cfg` logic correctly sets the `X-Account-ID` header.
|
||||||
|
|
||||||
|
* If a request doesn't need an account (e.g., public site data), set the `X-No-Account-ID: bypass` header.
|
||||||
|
* If using a temporary token, use the `x_no_account_id_token` query parameter.
|
||||||
Reference in New Issue
Block a user