176 lines
6.4 KiB
Markdown
Executable File
176 lines
6.4 KiB
Markdown
Executable File
|
|
# Aether API v3.x (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. |