# Aether API v3.00.20 (FastAPI)

The **Aether API** is a high-performance, multi-tenant backend for the Aether Platform, built on Python **FastAPI**. It powers both legacy and modern (V3/V4) applications, and is now fully containerized for robust, scalable deployment.

---


---

## 🏗️ Architecture Overview

The API is in transition from legacy (V1/V2) to the modern **V3 CRUD Architecture**. All new development follows V3 standards.


### V3 CRUD (Modern)
- **Path:** `/v3/crud/`
- **Principles:**
    - **String IDs:** All public APIs use `id_random` (URL-safe string IDs); internal integer IDs are hidden.
    - **Nested URLs:** Parent-child relationships enforced in URL structure.
    - **Advanced Search:** POST-based, recursive, with standardized operators.
    - **Schema Discovery:** Dynamic model/database introspection at `/v3/crud/{obj_type}/schema`.
    - **Granular Dependencies:** Specialized FastAPI dependencies for account context, pagination, filtering, serialization.


### V3 Actions
- **Path:** `/v3/action/`
- Handles complex/atomic business logic and binary operations outside standard CRUD.
- **Features:**
    - **Atomic Event Uploads:** File storage + event relations in one request.
    - **Content-Addressable Downloads:** SHA256-based file retrieval for high-performance caching.
    - **Intelligent ID Resolution:** Download endpoints auto-resolve container IDs.


### Legacy API (V1/V2)
- **Paths:** `/`, `/api/`, `/crud/`, `/v2/crud/`
- Maintained for backward compatibility, but being systematically deprecated. Accessing legacy routes triggers a warning in logs.

---


## 🛠️ Core Technologies
- **Framework:** FastAPI (v0.95.1+)
- **Database:** MariaDB (Docker, shared) + SQLAlchemy (v1.4.52)
- **Caching/ID Resolution:** Redis
- **Security:** JWT (JSON Web Tokens), API Key Machine Auth
- **Logging:** Structured, module-level, with rotation

---


## 🚀 Quick Start

The Aether API is designed for containerized deployment as part of the unified Aether Docker environment. For full-stack orchestration, see the documentation in the `aether_container_env` project.

### Prerequisites
- Docker & Docker Compose (for containerized use)
- Python 3.9+ (for local-only development)

### Local Development (Optional)
You can run the API locally for debugging:
```bash
virtualenv environment
source environment/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 5005 --reload
```
See [GUIDE__LOCAL_DEVELOPMENT.md](documentation/GUIDE__LOCAL_DEVELOPMENT.md) for details.

### Docker Usage
The API is run and managed via Docker Compose as part of the full Aether stack. Refer to the `aether_container_env` project for orchestration, environment setup, and advanced deployment instructions.

### Service Endpoints (Default Ports)
- **API Docs:** https://dev-api.oneskyit.com/docs
- **Frontend:** http://localhost:8888
- **phpMyAdmin:** http://localhost:8081 (if enabled)
- **Logs (Dozzle):** http://localhost:8881


---

## 🗄️ Database & Backups

All database operations are managed via Docker scripts in `aether_container_env/`:
- **Backup:** `./backup_db.sh` (saves to `backups/`)
- **Restore:** `./restore_db.sh [backup_file.gz]`
- **Export:** `./export_db.sh` (conference-ready backup)
- **Automated Import:** Drop file in `backups/import/` and run `./check_and_import.sh`

See [GUIDE__DEPLOYMENT_MANUAL.md](documentation/GUIDE__DEPLOYMENT_MANUAL.md) for full deployment and backup/restore instructions.

---


---

## 📂 Documentation Index

### **Architecture & Standards**
- [V3 Core Architecture](documentation/ARCH__V3_CORE.md): Modular structure and boot sequence.
- [V3 Development Standards](documentation/ARCH__V3_DEVELOPMENT_STANDARDS.md): ID Vision, inheritance, and naming rules.
- [Unified Agent Arch](documentation/ARCH__UNIFIED_AGENT.md): Vision for cross-stack AI agent awareness.

### **Integration Guides**
- [V3 Frontend API Guide](documentation/GUIDE__AE_API_V3_for_Frontend.md): How to use the V3 CRUD, Search, and Action endpoints.
- [V3 Frontend Websockets Guide](documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md): Websocket integration patterns.
- [Frontend Code Samples](documentation/FRONTEND_API_SAMPLES.md): TypeScript snippets for common API calls.

### **Security**
- [Project Security Hardening](documentation/PLAN__SECURITY_HARDENING.md): Path towards cryptographic JWT verification.

---


## 🧪 Testing Suite
Tests are under `tests/`:
- **Unit:** `tests/unit/` (mocked logic)
- **Integration:** `tests/integration/` (DB/Redis connectivity)
- **E2E:** `tests/e2e/` (API validation)
- **Docs:** [tests/README.md](tests/README.md)

---


## 🚧 Status & Work in Progress

### Active Workstreams
- **API Deprecation:** Pruning orphaned routers/methods
- **ID Vision:** String-ID standardization (Phase 2 complete)
- **V3 Migration:** Atomic event actions, hash-based file retrieval

### Known Issues
- **Badge Rendering:** Corrupted numeric `id` fields in `event_badge_template` can cause template load failures
- **Websockets:** Legacy modules need unification and stability improvements
- **Intermittent Timeouts:** Some E2E tests occasionally reproduce 403s/timeouts on nested GET calls

---


---

## 📜 Release Snapshot
Current Baseline: **`release/2026-01-28-v3_prod-snapshot`** (Stable v3.0.99)

---

## 🔐 Security & Access
- **SSH Required:** All git operations now require SSH (Bitbucket app passwords deprecated June 2026). See your Gitea or Bitbucket account for adding SSH keys.
- **Never commit secrets:** `.env` and credentials are git-ignored.
- **JWT Key:** Ensure `AE_API_JWT_KEY` is unique and high-entropy in production.
- **.env precedence:** API uses `.env` credentials for core infra (SMTP/DB) over DB settings.

---

## 🧑‍💻 Management & Operations
- **Restart API:** `docker compose restart ae_api`
- **Restart Frontend:** `docker compose restart ae_app`
- **Rebuild everything:** `docker compose up -d --build`
- **Logs:** http://localhost:8881 (Dozzle)
- **phpMyAdmin:** http://localhost:8081 (if enabled)

---

## 🏠 Directory Map (Key Mounts)
- `conf/` — Nginx/Gunicorn config templates
- `logs/` — Centralized logs
- `srv/` — Data/source code mounts
- `scripts/` — Automation scripts
- `backups/` — MariaDB snapshots

---

## 📝 Notes
- For multi-stack setups, ensure unique `AE_NETWORK_NAME` and `CONTAINER_` prefixes in `.env`.
- All stacks must connect to `aether_shared_net` for shared DB/Redis.
- See Docker env README and CHEATSHEET for advanced orchestration and troubleshooting.