Complete documentation for future sessions
- CLAUDE.md for AI agents to understand the codebase - GITEA-GUIDE.md centralizes all Gitea operations (API, Registry, Auth) - DEVELOPMENT-WORKFLOW.md explains complete dev process - ROADMAP.md, NEXT-SESSION.md for planning - QUICK-REFERENCE.md, TROUBLESHOOTING.md for daily use - 40+ detailed docs in /docs folder - Backend as submodule from Gitea Everything documented for autonomous operation. Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hector Ros
484
docs/02-backend/api-endpoints.md
Normal file
484
docs/02-backend/api-endpoints.md
Normal file
@@ -0,0 +1,484 @@
|
||||
# API Endpoints
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://localhost:3000/api
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
Todos los endpoints (excepto `/health`) requieren autenticación JWT:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Projects
|
||||
|
||||
### GET /projects
|
||||
|
||||
Lista todos los proyectos.
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"projects": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "My Project",
|
||||
"description": "Project description",
|
||||
"giteaRepoUrl": "http://gitea/owner/repo",
|
||||
"k8sNamespace": "my-project",
|
||||
"status": "active",
|
||||
"createdAt": "2026-01-19T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### GET /projects/:id
|
||||
|
||||
Obtiene detalles de un proyecto.
|
||||
|
||||
### POST /projects
|
||||
|
||||
Crea un nuevo proyecto.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"name": "My New Project",
|
||||
"description": "Project description",
|
||||
"dockerImage": "node:20-alpine",
|
||||
"envVars": {
|
||||
"NODE_ENV": "production"
|
||||
},
|
||||
"replicas": 2,
|
||||
"cpuLimit": "1000m",
|
||||
"memoryLimit": "1Gi"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"project": {
|
||||
"id": "uuid",
|
||||
"name": "My New Project",
|
||||
"giteaRepoUrl": "http://gitea/owner/my-new-project",
|
||||
"k8sNamespace": "my-new-project-abc123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH /projects/:id
|
||||
|
||||
Actualiza un proyecto.
|
||||
|
||||
### DELETE /projects/:id
|
||||
|
||||
Elimina un proyecto y todos sus recursos.
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### GET /tasks
|
||||
|
||||
Lista tareas con filtros opcionales.
|
||||
|
||||
**Query params**:
|
||||
- `projectId`: Filtrar por proyecto
|
||||
- `state`: Filtrar por estado (`backlog`, `in_progress`, etc.)
|
||||
- `assignedAgentId`: Filtrar por agente
|
||||
- `limit`: Límite de resultados (default: 50)
|
||||
- `offset`: Offset para paginación
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"projectId": "uuid",
|
||||
"title": "Implement login",
|
||||
"description": "Create authentication system",
|
||||
"state": "in_progress",
|
||||
"priority": "high",
|
||||
"assignedAgentId": "agent-123",
|
||||
"branchName": "task-abc-implement-login",
|
||||
"prNumber": 42,
|
||||
"prUrl": "http://gitea/owner/repo/pulls/42",
|
||||
"previewUrl": "https://task-abc.preview.aiworker.dev",
|
||||
"createdAt": "2026-01-19T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 10,
|
||||
"limit": 50,
|
||||
"offset": 0
|
||||
}
|
||||
```
|
||||
|
||||
### GET /tasks/:id
|
||||
|
||||
Obtiene detalles completos de una tarea incluyendo preguntas.
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": "uuid",
|
||||
"title": "Implement login",
|
||||
"state": "needs_input",
|
||||
"questions": [
|
||||
{
|
||||
"id": "q-uuid",
|
||||
"question": "Which auth library should I use?",
|
||||
"context": "Need to choose between JWT or session-based",
|
||||
"askedAt": "2026-01-19T11:00:00Z",
|
||||
"status": "pending"
|
||||
}
|
||||
],
|
||||
"project": {
|
||||
"name": "My Project",
|
||||
"giteaRepoUrl": "..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /tasks
|
||||
|
||||
Crea una nueva tarea.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"projectId": "uuid",
|
||||
"title": "Implement feature X",
|
||||
"description": "Detailed description...",
|
||||
"priority": "high"
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH /tasks/:id
|
||||
|
||||
Actualiza una tarea.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"state": "approved",
|
||||
"notes": "Looks good!"
|
||||
}
|
||||
```
|
||||
|
||||
### POST /tasks/:id/respond
|
||||
|
||||
Responde a una pregunta del agente.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"questionId": "q-uuid",
|
||||
"response": "Use JWT with jsonwebtoken library"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"question": {
|
||||
"id": "q-uuid",
|
||||
"status": "answered",
|
||||
"respondedAt": "2026-01-19T11:05:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /tasks/:id/approve
|
||||
|
||||
Aprueba una tarea en estado `ready_to_test`.
|
||||
|
||||
### POST /tasks/:id/reject
|
||||
|
||||
Rechaza una tarea y la regresa a `in_progress`.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"reason": "Needs more tests"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Groups (Merges)
|
||||
|
||||
### POST /task-groups
|
||||
|
||||
Crea un grupo de tareas para merge a staging/production.
|
||||
|
||||
**Body**:
|
||||
```json
|
||||
{
|
||||
"projectId": "uuid",
|
||||
"taskIds": ["task-1", "task-2", "task-3"],
|
||||
"targetBranch": "staging",
|
||||
"notes": "Sprint 1 features"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"taskGroup": {
|
||||
"id": "uuid",
|
||||
"taskIds": ["task-1", "task-2", "task-3"],
|
||||
"status": "pending",
|
||||
"stagingBranch": "release/sprint-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /task-groups/:id
|
||||
|
||||
Obtiene detalles de un task group.
|
||||
|
||||
### POST /task-groups/:id/deploy-staging
|
||||
|
||||
Despliega el task group a staging.
|
||||
|
||||
### POST /task-groups/:id/deploy-production
|
||||
|
||||
Despliega el task group a production.
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
### GET /agents
|
||||
|
||||
Lista todos los agentes.
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"agents": [
|
||||
{
|
||||
"id": "agent-123",
|
||||
"podName": "claude-agent-abc123",
|
||||
"status": "busy",
|
||||
"currentTaskId": "task-uuid",
|
||||
"capabilities": ["javascript", "react", "node"],
|
||||
"tasksCompleted": 42,
|
||||
"lastHeartbeat": "2026-01-19T12:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### GET /agents/:id
|
||||
|
||||
Obtiene detalles de un agente incluyendo logs recientes.
|
||||
|
||||
### GET /agents/:id/logs
|
||||
|
||||
Obtiene logs del agente.
|
||||
|
||||
**Query params**:
|
||||
- `limit`: Número de logs (default: 100)
|
||||
- `level`: Filtrar por nivel (`debug`, `info`, `warn`, `error`)
|
||||
|
||||
---
|
||||
|
||||
## Deployments
|
||||
|
||||
### GET /deployments
|
||||
|
||||
Lista deployments con filtros.
|
||||
|
||||
**Query params**:
|
||||
- `projectId`: Filtrar por proyecto
|
||||
- `environment`: Filtrar por entorno
|
||||
- `status`: Filtrar por estado
|
||||
|
||||
### GET /deployments/:id
|
||||
|
||||
Obtiene detalles de un deployment.
|
||||
|
||||
### POST /deployments/:id/rollback
|
||||
|
||||
Hace rollback de un deployment.
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"rollbackDeploymentId": "new-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health & Status
|
||||
|
||||
### GET /health
|
||||
|
||||
Health check del backend.
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2026-01-19T12:00:00Z",
|
||||
"services": {
|
||||
"mysql": "connected",
|
||||
"redis": "connected",
|
||||
"gitea": "reachable",
|
||||
"kubernetes": "connected"
|
||||
},
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /metrics
|
||||
|
||||
Métricas del sistema (Prometheus format).
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Events
|
||||
|
||||
Conectar a: `ws://localhost:3000`
|
||||
|
||||
### Client → Server
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "auth",
|
||||
"data": {
|
||||
"token": "jwt-token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "subscribe",
|
||||
"data": {
|
||||
"projectId": "uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Server → Client
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "task:created",
|
||||
"data": {
|
||||
"taskId": "uuid",
|
||||
"projectId": "uuid",
|
||||
"title": "New task"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "task:status_changed",
|
||||
"data": {
|
||||
"taskId": "uuid",
|
||||
"oldState": "in_progress",
|
||||
"newState": "ready_to_test",
|
||||
"previewUrl": "https://..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "task:needs_input",
|
||||
"data": {
|
||||
"taskId": "uuid",
|
||||
"questionId": "q-uuid",
|
||||
"question": "Which library?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "agent:status",
|
||||
"data": {
|
||||
"agentId": "agent-123",
|
||||
"status": "idle",
|
||||
"lastTaskId": "task-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "deploy:started",
|
||||
"data": {
|
||||
"deploymentId": "uuid",
|
||||
"environment": "staging"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "deploy:completed",
|
||||
"data": {
|
||||
"deploymentId": "uuid",
|
||||
"environment": "staging",
|
||||
"url": "https://staging-project.aiworker.dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
Todos los endpoints pueden retornar estos errores:
|
||||
|
||||
### 400 Bad Request
|
||||
```json
|
||||
{
|
||||
"error": "Validation error",
|
||||
"details": {
|
||||
"field": "projectId",
|
||||
"message": "Required"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 401 Unauthorized
|
||||
```json
|
||||
{
|
||||
"error": "Invalid or expired token"
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
```json
|
||||
{
|
||||
"error": "Resource not found"
|
||||
}
|
||||
```
|
||||
|
||||
### 500 Internal Server Error
|
||||
```json
|
||||
{
|
||||
"error": "Internal server error",
|
||||
"requestId": "req-uuid"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user