112 lines
3.1 KiB
Markdown
112 lines
3.1 KiB
Markdown
# Документ 08. API Specification
|
||
|
||
## Назначение
|
||
|
||
Документ определяет стандарты REST API платформы Agent Control Center,
|
||
правила проектирования endpoint'ов, форматы данных и требования к
|
||
совместимости.
|
||
|
||
# 1. Общие принципы
|
||
|
||
- REST API с JSON.
|
||
- OpenAPI 3.1.
|
||
- Версионирование через `/api/v1`.
|
||
- UTF-8.
|
||
- UTC для дат и времени.
|
||
- UUID как идентификаторы ресурсов.
|
||
|
||
# 2. Аутентификация
|
||
|
||
Поддерживаются: - OAuth2/OIDC; - Bearer Token; - API Keys (для сервисных
|
||
интеграций).
|
||
|
||
Каждый запрос должен содержать корректные учетные данные, если ресурс не
|
||
является публичным.
|
||
|
||
# 3. Структура URL
|
||
|
||
Примеры:
|
||
|
||
- GET /api/v1/projects
|
||
- POST /api/v1/projects
|
||
- GET /api/v1/projects/{project_id}
|
||
- PATCH /api/v1/projects/{project_id}
|
||
- DELETE /api/v1/projects/{project_id}
|
||
|
||
Аналогичная структура используется для: - workspaces; - tasks; - runs; -
|
||
agents; - connectors; - artifacts; - memories; - approvals.
|
||
|
||
# 4. Правила запросов
|
||
|
||
- Использовать HTTP-методы по назначению.
|
||
- Поддерживать пагинацию.
|
||
- Поддерживать фильтрацию.
|
||
- Поддерживать сортировку.
|
||
- Поддерживать идемпотентность для повторяемых операций.
|
||
|
||
# 5. Формат ответов
|
||
|
||
Успешный ответ:
|
||
|
||
``` json
|
||
{
|
||
"data": {},
|
||
"meta": {
|
||
"request_id": "uuid"
|
||
}
|
||
}
|
||
```
|
||
|
||
Ошибка:
|
||
|
||
``` json
|
||
{
|
||
"error": {
|
||
"code": "ACC-4001",
|
||
"message": "Validation failed"
|
||
},
|
||
"meta": {
|
||
"request_id": "uuid"
|
||
}
|
||
}
|
||
```
|
||
|
||
# 6. Коды ошибок
|
||
|
||
- 400 Bad Request
|
||
- 401 Unauthorized
|
||
- 403 Forbidden
|
||
- 404 Not Found
|
||
- 409 Conflict
|
||
- 422 Validation Error
|
||
- 429 Too Many Requests
|
||
- 500 Internal Server Error
|
||
|
||
Коды ошибок должны соответствовать отдельному каталогу ошибок.
|
||
|
||
# 7. Версионирование
|
||
|
||
- `/api/v1` --- стабильная версия.
|
||
- Несовместимые изменения требуют новой версии API.
|
||
- Устаревшие версии сопровождаются периодом депрекации.
|
||
|
||
# 8. Идемпотентность
|
||
|
||
Для операций создания и запуска рекомендуется поддерживать заголовок
|
||
`Idempotency-Key`.
|
||
|
||
# 9. Трассировка
|
||
|
||
Каждый запрос должен иметь: - request_id; - correlation_id (при наличии
|
||
распределенных операций).
|
||
|
||
# 10. Документация
|
||
|
||
- OpenAPI спецификация генерируется автоматически.
|
||
- `/docs` --- Swagger UI.
|
||
- `/redoc` --- ReDoc.
|
||
- `/openapi.json` --- машинное описание API.
|
||
|
||
## Следующий документ
|
||
|
||
09_Event_Bus.md
|