71 lines
2.6 KiB
Markdown
71 lines
2.6 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. 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).
|
|
|