docs: initial project documentation

- architecture overview and stack - project structure and development order - API design (endpoints, models, runtimes) - infrastructure overview (k8s cluster, S3, registry) - decisions log with rationale - progress tracker v1/v2
2026-03-06 09:51:01 +04:00
commit b29b6c3d10
7 changed files with 344 additions and 0 deletions
@@ -0,0 +1,95 @@
+# API Design
+
+## Базовый URL
+
+```
+https://sless.api.ngcloud.ru/v1
+```
+
+## Аутентификация
+
+```
+Authorization: Bearer <cloud-token>
+```
+
+## Ресурсы
+
+### Functions
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions | Список функций |
+| POST | /functions | Создать функцию |
+| GET | /functions/{id} | Получить функцию |
+| PUT | /functions/{id} | Обновить функцию |
+| DELETE | /functions/{id} | Удалить функцию |
+
+### Versions (код функции)
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions/{id}/versions | Список версий |
+| POST | /functions/{id}/versions | Загрузить новый код (multipart zip) |
+| GET | /functions/{id}/versions/{ver} | Получить версию |
+| POST | /functions/{id}/versions/{ver}/activate | Активировать версию |
+
+### Triggers
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions/{id}/triggers | Список триггеров |
+| POST | /functions/{id}/triggers | Создать триггер (HTTP/Cron) |
+| DELETE | /functions/{id}/triggers/{tid} | Удалить триггер |
+
+### Invocations (вызов и логи)
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| POST | /functions/{id}/invoke | Синхронный вызов |
+| GET | /functions/{id}/invocations | История вызовов |
+| GET | /functions/{id}/invocations/{iid} | Детали вызова + логи |
+
+## Поддерживаемые runtime (v1)
+
+- `go1.21`
+- `python3.11`
+- `nodejs20`
+
+## Модель Function
+
+```json
+{
+  "id": "fn-uuid",
+  "name": "my-function",
+  "description": "...",
+  "runtime": "python3.11",
+  "entrypoint": "handler.handle",
+  "memory_mb": 128,
+  "timeout_sec": 30,
+  "env_vars": {"KEY": "value"},
+  "active_version": "1",
+  "status": "active",
+  "created_at": "...",
+  "updated_at": "..."
+}
+```
+
+## Модель Trigger
+
+```json
+{
+  "id": "tr-uuid",
+  "type": "http",
+  "url": "https://sless.api.ngcloud.ru/invoke/fn-uuid",
+  "created_at": "..."
+}
+```
+
+```json
+{
+  "id": "tr-uuid",
+  "type": "cron",
+  "schedule": "0 * * * *",
+  "created_at": "..."
+}
+```