17a627a981
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 .
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# 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_random>`
|
|
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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 5. 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).
|
|
|