chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
487
docs/api-mvp.md
Normal file
487
docs/api-mvp.md
Normal file
@@ -0,0 +1,487 @@
|
||||
---
|
||||
title: API Specification (MVP) — DAARION.city & MicroDAO
|
||||
version: 1.0.0
|
||||
status: canonical
|
||||
last_updated: 2024-11-14
|
||||
---
|
||||
|
||||
# API Specification (MVP) — DAARION.city & MicroDAO
|
||||
|
||||
**Документ описує мінімальний набір API-ендпоінтів для запуску MVP-версії MicroDAO, інтегрованої з DAARION.city.**
|
||||
|
||||
Фокус:
|
||||
|
||||
* створення та реєстрація MicroDAO
|
||||
* робота з реєстром DAO та платформ
|
||||
* базові операції Wallet (DAAR/DAARION)
|
||||
* реєстрація вендорів та створення платформ
|
||||
* PDP-перевірки
|
||||
* базові Agent / Router виклики (stub-рівень)
|
||||
|
||||
---
|
||||
|
||||
# 1. Загальні принципи
|
||||
|
||||
* Транспорт: **HTTPS / JSON**
|
||||
* Auth: **Bearer Token (user / service token)**
|
||||
* Стиль: REST-like з чіткими ресурсами
|
||||
* Усі критичні операції проходять через PDP
|
||||
* Ідентифікатори DAO/платформ/користувачів — `UUID` / `string` (визначається реалізацією)
|
||||
|
||||
Базовий префікс:
|
||||
|
||||
```text
|
||||
/api/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 2. Auth & Context
|
||||
|
||||
Контекст користувача / сервісу визначається:
|
||||
|
||||
* токеном авторизації (user/service)
|
||||
* DAO-контекстом (якщо вказано `X-DAO-ID` у заголовках)
|
||||
|
||||
Приклад заголовків:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
X-DAO-ID: <dao_id> # опційно, якщо дія виконується в межах конкретного DAO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 3. DAOFactory API
|
||||
|
||||
## 3.1 Створення MicroDAO
|
||||
|
||||
**POST** `/api/v1/dao`
|
||||
|
||||
Створює новий MicroDAO (A3 або A4).
|
||||
|
||||
### Умови
|
||||
|
||||
* PDP: `policy.dao.create`
|
||||
* токен користувача
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"description": "string",
|
||||
"type": "public | private",
|
||||
"level": "A3 | A4",
|
||||
"settings": {
|
||||
"visibility": "catalog | invite-only"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"dao_id": "string",
|
||||
"level": "A3 | A4",
|
||||
"name": "string",
|
||||
"parent_dao_id": null,
|
||||
"federation_mode": "none",
|
||||
"created_at": "2025-..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.2 Отримати DAO за id
|
||||
|
||||
**GET** `/api/v1/dao/{dao_id}`
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"dao_id": "string",
|
||||
"name": "string",
|
||||
"description": "string",
|
||||
"level": "A1 | A2 | A3 | A4",
|
||||
"type": "platform | public | private",
|
||||
"parent_dao_id": "string | null",
|
||||
"federation_mode": "none | member | superdao",
|
||||
"settings": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.3 Список DAO (каталог)
|
||||
|
||||
**GET** `/api/v1/dao`
|
||||
|
||||
Параметри:
|
||||
|
||||
* `level` (опційно): `A1|A2|A3|A4`
|
||||
* `type` (опційно): `platform|public|private`
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"dao_id": "string",
|
||||
"name": "string",
|
||||
"level": "A2",
|
||||
"type": "platform"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 4. Registry API (DAO & Platforms)
|
||||
|
||||
## 4.1 Реєстр платформ (тільки A2)
|
||||
|
||||
**GET** `/api/v1/platforms`
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"dao_id": "string",
|
||||
"name": "Helion",
|
||||
"slug": "helion",
|
||||
"description": "Energy platform",
|
||||
"level": "A2"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. Wallet API (DAAR / DAARION)
|
||||
|
||||
## 5.1 Отримати баланс користувача
|
||||
|
||||
**GET** `/api/v1/wallet/me`
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"balances": [
|
||||
{ "symbol": "DAAR", "amount": "123.45" },
|
||||
{ "symbol": "DAARION", "amount": "0.50" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5.2 Перевірка базових прав доступу (допоміжний метод)
|
||||
|
||||
**POST** `/api/v1/wallet/check-access`
|
||||
|
||||
Перевіряє, чи достатньо токенів для певної дії (корисно для UI).
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"check": "dao.create | vendor.register | platform.create"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed": true,
|
||||
"reason": null
|
||||
}
|
||||
```
|
||||
|
||||
або
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed": false,
|
||||
"reason": "INSUFFICIENT_DAARION_BALANCE"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. Vendor & Platform API
|
||||
|
||||
## 6.1 Реєстрація вендора на платформі
|
||||
|
||||
**POST** `/api/v1/platforms/{platform_id}/vendors`
|
||||
|
||||
### Умови
|
||||
|
||||
* PDP: `policy.vendor.register` (мінімум 0.01 DAARION у стейкінгу)
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "GreenFarm UA",
|
||||
"contact": {
|
||||
"email": "owner@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor_id": "string",
|
||||
"platform_id": "string",
|
||||
"status": "approved | pending"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Створення платформи (A2)
|
||||
|
||||
**POST** `/api/v1/platforms`
|
||||
|
||||
### Умови
|
||||
|
||||
* PDP: `policy.platform.create` (мінімум 1 DAARION у стейкінгу)
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Helion",
|
||||
"slug": "helion",
|
||||
"description": "Energy platform",
|
||||
"domain": "energy"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"dao_id": "string",
|
||||
"name": "Helion",
|
||||
"level": "A2",
|
||||
"type": "platform"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 7. PDP API
|
||||
|
||||
## 7.1 Перевірка політики
|
||||
|
||||
**POST** `/api/v1/pdp/check`
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"policy": "policy.dao.create",
|
||||
"resource": {
|
||||
"type": "dao",
|
||||
"id": null
|
||||
},
|
||||
"context": {
|
||||
"dao_level": "A3",
|
||||
"user_id": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "allow | deny | require-elevation",
|
||||
"reason": "string | null"
|
||||
}
|
||||
```
|
||||
|
||||
> У продакшн-коді сервіси зазвичай викликають PDP напряму, а не через публічний API. Ендпоінт може використовуватись для діагностики, дебагу або внутрішніх адміністративних інструментів.
|
||||
|
||||
---
|
||||
|
||||
# 8. Agents & Router API (MVP Stub)
|
||||
|
||||
## 8.1 Запуск агента в DAO (simple invoke)
|
||||
|
||||
**POST** `/api/v1/dao/{dao_id}/agents/{agent_id}/invoke`
|
||||
|
||||
### Умови
|
||||
|
||||
* PDP: `policy.agent.run`
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"input": "string",
|
||||
"metadata": {
|
||||
"origin": "admin-console | user-chat | system"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "string",
|
||||
"status": "queued | running | completed | failed",
|
||||
"output": "string | null"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8.2 Створення Router flow (спрощено)
|
||||
|
||||
**POST** `/api/v1/router/flows`
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"dao_id": "string",
|
||||
"name": "Onboard new member",
|
||||
"steps": [
|
||||
{ "type": "agent", "agent_id": "welcome-agent" },
|
||||
{ "type": "agent", "agent_id": "policy-explainer" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_id": "string",
|
||||
"status": "created"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 9. Events (System → Clients)
|
||||
|
||||
Події можуть відправлятися через Webhook / WebSocket / NATS (деталі реалізації залежать від інфраструктури).
|
||||
|
||||
Мінімальний набір подій:
|
||||
|
||||
* `dao.created`
|
||||
* `platform.created`
|
||||
* `vendor.registered`
|
||||
* `agent.run.completed`
|
||||
|
||||
Приклад payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "dao.created",
|
||||
"data": {
|
||||
"dao_id": "string",
|
||||
"name": "string",
|
||||
"level": "A3",
|
||||
"created_by": "user_id"
|
||||
},
|
||||
"ts": "2025-..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 10. Статуси та помилки
|
||||
|
||||
## 10.1 HTTP-статуси
|
||||
|
||||
* `200 OK` — успішний запит
|
||||
* `201 Created` — ресурс створено
|
||||
* `400 Bad Request` — некоректні дані
|
||||
* `401 Unauthorized` — відсутня/некоректна авторизація
|
||||
* `403 Forbidden` — PDP = deny
|
||||
* `404 Not Found` — ресурс не знайдено
|
||||
* `409 Conflict` — конфлікт станів
|
||||
* `500 Internal Server Error` — внутрішня помилка
|
||||
|
||||
## 10.2 Приклад помилки
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "ACCESS_DENIED",
|
||||
"message": "PDP denied action 'platform.create' for this user.",
|
||||
"details": {
|
||||
"policy": "policy.platform.create"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 11. Подальший розвиток API
|
||||
|
||||
Цей документ описує **MVP-шар**. Надалі можливі розширення:
|
||||
|
||||
* детальний Wallet API (транзакції, стейкінг, payout-и)
|
||||
* повна OpenAPI-специфікація
|
||||
* окремий Agent Runtime API (streams, tools, multi-step flows)
|
||||
* Notification API (email / push / in-app)
|
||||
|
||||
На рівні MVP цього набору достатньо, щоб:
|
||||
|
||||
* створювати DAO
|
||||
* реєструвати платформи
|
||||
* реєструвати вендорів
|
||||
* керувати базовими правами доступу
|
||||
* запускати прості агенти та оркестраційні флоу.
|
||||
|
||||
---
|
||||
|
||||
## 12. Integration with Other Docs
|
||||
|
||||
Цей документ інтегрується з:
|
||||
|
||||
- `api.md` — повна API специфікація (розширена версія)
|
||||
- `core-services-mvp.md` — реалізація core-сервісів (Wallet, DAOFactory, Registry, PDP)
|
||||
- `pdp_access.md` — PDP та система доступів
|
||||
- `microdao-architecture.md` — архітектура A1-A4
|
||||
- `superdao-federation.md` — SuperDAO та федерації
|
||||
- `tokenomics/city-tokenomics.md` — токеноміка
|
||||
|
||||
---
|
||||
|
||||
## 13. Changelog
|
||||
|
||||
### v1.0.0 — 2024-11-14
|
||||
- Початкова версія MVP API специфікації
|
||||
- Додано DAOFactory API (створення, отримання, список DAO)
|
||||
- Додано Registry API (реєстр платформ)
|
||||
- Додано Wallet API (баланси, перевірка доступу)
|
||||
- Додано Vendor & Platform API (реєстрація вендорів, створення платформ)
|
||||
- Додано PDP API (перевірка політик)
|
||||
- Додано Agents & Router API (stub-рівень)
|
||||
- Додано Events (системні події)
|
||||
|
||||
---
|
||||
|
||||
**Версія:** 1.0.0
|
||||
**Останнє оновлення:** 2024-11-14
|
||||
*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.*
|
||||
|
||||
Reference in New Issue
Block a user