Files

Scott Idem 17a627a981 feat: Implement Event File Hosted Data Fix and API Guide Update

Address critical data visibility issues for Event Files and enhance frontend documentation.

This commit resolves the persistent problem where top-level hosted file convenience fields
(e.g., , , ) were
returning as  in V3 Event File API responses, even when .

Key changes include:
- Refactored  Pydantic model:
    - Removed redundant  definitions from top-level hosted file convenience fields,
      allowing direct mapping from SQL view columns.
    - Simplified  to focus solely on conditionally loading the nested
       object, as top-level fields are now populated directly by Pydantic
      from the  view.
    - Added comprehensive comments to clarify data flow, Pydantic's behavior, and the
      expected origin of these convenience fields from SQL views.
- Updated :
    - Introduced a new section detailing how to retrieve Event File data, including the
      use of  to get both top-level convenience fields and a nested
       object.
    - Clarified all ID references as random string IDs.
    - Renumbered the troubleshooting section.
- Copied updated guide to .
- Continued ID Vision compliance audit, ensuring consistent handling of random string IDs
  across various core and event models (Account, Address, Contact, DataStore, Event Badge Template).
- Consolidated ID Vision E2E tests and updated related documentation.
- Minor updates to  and
  to support Event File data retrieval with .

2026-02-19 15:22:17 -05:00

3.7 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.).

Standard Access: Provide the x-account-id (the random string ID).
- Header: x-account-id: <account_id_random>
Administrative Bypass: For authorized scripts needing global access.
- Header: x-no-account-id: bypass
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 and site_id random strings.
** ڈیزائن 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_random}
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.

4. Event File Data Retrieval (Hosted Files)

Event Files (event_file) often have associated Hosted Files (hosted_file) which contain binary data and metadata like SHA256 hashes, content types, and sizes. To retrieve this additional data:

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

Response Impact:

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)
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.

5. Troubleshooting 403 Forbidden

If you receive a 403 on a valid ID:

Verify x-aether-api-key is correct.
Ensure you are sending x-account-id and NOT x-aether-api-token.
Verify the record actually belongs to the account ID you are sending.
Check if the object is marked public_read: True in the registry. (Posts and Archive Content allow guest access; Journals and Badges do not).

3.7 KiB Raw Blame History