Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee500a9ad5d58db6967dbcdbdf1f48bae55016d4
OSIT-AE-App-Svelte/documentation/GUIDE__AE_API_V3_for_Frontend.md
Scott Idem ee500a9ad5 Saving notes and things
2026-02-26 18:52:15 -05:00

9.1 KiB
Raw Blame History

Aether API V3 Frontend Integration Guide (Svelte/TypeScript)

This guide defines the standards for interacting with the Aether API V3 CRUD and Action endpoints.

1. Authentication and Security (Mandatory)

V3 architecture enforces strict Multi-Tenant Isolation and Machine Authorization. Requests require two levels of validation.

A. The "Entry Ticket" (API Key)

Mandatory for all requests. identifies the application or client.

  • Header: x-aether-api-key: <your_app_key>
  • Status Code: 403 Forbidden if missing or invalid.

B. The "Visa" (Account Context)

Required for any non-public data (Journals, Badges, Users, etc.).

  1. Standard Access: Provide the x-account-id (the random string ID).
    • Header: x-account-id: <account_id>
  2. Administrative Bypass: For authorized scripts needing global access.
    • Header: x-no-account-id: bypass
  3. Token Access: Provide a JWT in the query string.
    • Query Param: ?jwt=<token>

Caution

UNSUPPORTED HEADERS: The header x-aether-api-token is NOT recognized by the V3 API. If you send it, the backend will treat you as a guest and block access to private data.

2. Bootstrapping (The FQDN Handshake)

When the frontend first loads and doesn't know the account_id, it performs a "handshake" using its domain name.

Endpoint: POST /v3/crud/site_domain/search Body:

{
  "and": [
    { "field": "fqdn", "op": "eq", "value": "demo.oneskyit.com" }
  ]
}

Results:

  • Returns 200 + a list containing the account_id (random string ID) and site_id (random string ID).
  • ** デザイン Choice:** If the domain is not found, it returns 200 OK with an empty list []. It is NOT a 404.

3. Standard CRUD Patterns

A. GET by ID

Used when the ID is known.

  • Endpoint: GET /v3/crud/{obj_type}/{id}
  • Security: Returns 403 if the record doesn't belong to your x-account-id.

B. POST Search

The primary way to retrieve data.

  • Endpoint: POST /v3/crud/{obj_type}/search
  • Security: Automatically filters results to only show records belonging to your x-account-id. If no account context is provided, it will return 0 records for private objects.

C. POST Create / PATCH Update

Modify data in the system.

  • Endpoints:
    • POST /v3/crud/{obj_type}/
    • PATCH /v3/crud/{obj_type}/{id}
  • Strict Mode (Default): The API validates your payload against the Pydantic model. If you send fields that do not exist in the model, the database might return a 400 "Unknown column" error.
  • Permissive Mode (Header): To allow the frontend to send "extra" fields (like local UI state) without causing errors, use the following header:
    • Header: x-ae-ignore-extra-fields: true
    • Behavior: When set to true, the backend will automatically strip any fields from the payload that are not defined in the object's model before attempting to save to the database.

4. Flat vs Nested URL Paths

This is the single most common source of mock errors in Playwright tests. The V3 API has two URL structures and the right one to use depends on the object type and the operation.

Always-Flat Objects

These object types use flat paths for every operation — GET, list, search, create, update, delete. They are never children in a nested URL.

Core modules: account, activity_log, address, contact, hosted_file, organization, page, person, site, user

Other modules: archive, event, journal, post

All operations for these objects use the flat helpers:

Operation Function URL pattern
GET single api.get_ae_obj_v3 /v3/crud/{obj_type}/{id}
GET list api.get_ae_obj_li_v3 /v3/crud/{obj_type}/?for_obj_id=...
Search api.search_ae_obj_v3 /v3/crud/{obj_type}/search
Create api.create_ae_obj_v3 /v3/crud/{obj_type}/
Update api.patch_ae_obj_v3 /v3/crud/{obj_type}/{id}
Delete api.delete_ae_obj_v3 /v3/crud/{obj_type}/{id}

Nested Objects (Event Sub-objects)

Objects that belong to a parent (e.g. event_badge, event_session, event_badge_template, event_file, event_presenter, event_presentation, event_device, event_location) use nested paths for mutations but flat paths for reads.

Operation Function URL pattern
GET single api.get_ae_obj_v3 /v3/crud/{obj_type}/{id} ← flat
GET list api.get_ae_obj_li_v3 /v3/crud/{obj_type}/?for_obj_id=... ← flat
Search api.search_ae_obj_v3 /v3/crud/{obj_type}/search ← flat
Create api.create_nested_obj_v3 /v3/crud/{parent_type}/{parent_id}/{child_type}/ ← nested
Update api.update_nested_obj_v3 /v3/crud/{parent_type}/{parent_id}/{child_type}/{child_id} ← nested
Delete api.delete_ae_obj_v3 /v3/crud/{obj_type}/{id} ← flat

Example — event_badge under event abc123:

GET    /v3/crud/event_badge/badge-xyz          ← flat (get_ae_obj_v3)
GET    /v3/crud/event_badge/?for_obj_id=abc123 ← flat (get_ae_obj_li_v3)
POST   /v3/crud/event_badge/search             ← flat (search_ae_obj_v3)
POST   /v3/crud/event/abc123/event_badge/      ← nested (create_nested_obj_v3)
PATCH  /v3/crud/event/abc123/event_badge/badge-xyz  ← nested (update_nested_obj_v3)
DELETE /v3/crud/event_badge/badge-xyz          ← flat (delete_ae_obj_v3)

Playwright Mock Rule of Thumb

Since all reads are flat, the most common mock patterns are:

// ✅ Search (always flat)
url.includes('/v3/crud/event_badge/search') && method === 'POST'

// ✅ List (always flat, filter by query param)
url.includes('/v3/crud/event_badge/') && url.includes('for_obj_id') && method === 'GET'

// ✅ GET single (always flat)
url.includes('/v3/crud/event_badge/badge-xyz') && method === 'GET'

// ✅ Create (nested for event sub-objects)
url.match(/\/v3\/crud\/event\/[^/]+\/event_badge\/$/) && method === 'POST'

// ✅ Update (nested for event sub-objects)
url.match(/\/v3\/crud\/event\/[^/]+\/event_badge\/badge-xyz/) && method === 'PATCH'

5. V3 Uniform Lookup System

The V3 Lookup system provides a hierarchical, deduplicated interface for standardized tables (Countries, Timezones, etc.). It supports global defaults, account overrides, and site-specific whitelisting.

A. List Lookups

Retrieve a ranked and filtered list of lookup items.

  • Endpoint: GET /v3/lookup/{lu_type}/list
  • Available Types: country, country_subdivision, time_zone
  • Parameters:
    • site_id (Optional): Random ID of the site to apply a Whitelist Policy.
    • only_priority (Optional): Set to true to return only high-priority items (e.g., common time zones).
    • for_type / for_id (Optional): Context for object-specific overrides.
    • include_disabled (Optional): Set to true to see shadowed/disabled records.

B. Resolve Identity

Resolves a string (code, group, or name) to a single record.

  • Endpoint: GET /v3/lookup/{lu_type}/resolve?q=VALUE
  • Usage: Use this when you have an external code (e.g., ISO "US") and need the full Aether record.

C. Site Whitelist Policy

To limit lookups for a specific site, add a lookup_policy to the site.cfg_json field. Schema:

{
  "lookup_policy": {
    "country": ["US", "CA", "GB"],
    "time_zone": ["America/New_York"]
  }
}

Note: Whitelist values must match the group field in the database.

6. Event File Data Retrieval (Hosted Files)

Every Event File (event_file) must have a linked Hosted File (hosted_file). The Hosted File itself is a metadata record for binary content (files), which is accessed via separate Action endpoints (e.g., /v3/action/hosted_file/download). This API endpoint provides metadata about the associated hosted file. To retrieve this additional metadata:

  • Endpoint: GET /v3/crud/event_file/{event_file_id}
  • Query Parameter: Add inc_hosted_file=true
    • Example: /v3/crud/event_file/<event_file_id>?inc_hosted_file=true

Response Impact:

  1. Top-Level Convenience Fields: The response will include top-level fields for commonly needed hosted file data. These are populated directly from the SQL view via JOINs.
    • hosted_file_hash_sha256 (string)
    • hosted_file_subdirectory_path (string)
    • hosted_file_content_type (string)
    • hosted_file_size (string - in bytes)
  2. Nested Hosted File Object: A full hosted_file object will be nested under the hosted_file key. This object (Hosted_File_Base model) will contain all its standard fields, including id (random string ID), hash_sha256, content_type, size, etc.

7. Troubleshooting 403 Forbidden

If you receive a 403 on a valid ID:

  1. Verify x-aether-api-key is correct.
  2. Ensure you are sending x-account-id and NOT x-aether-api-token.
  3. Verify the record actually belongs to the account ID you are sending.
  4. Check if the object is marked public_read: True in the registry. (Posts and Archive Content allow guest access; Journals and Badges do not).
Reference in New Issue View Git Blame Copy Permalink