Task Management API Endpoints

[starbops]

Task Management API Endpoints

User Story

As a developer, I want comprehensive task management APIs so that I can create, monitor, and manage code execution tasks.

Technical Requirements

• Implement task creation with validation
• Build task retrieval with pagination and filtering
• Create task status update mechanisms
• Add task deletion with proper authorization
• Implement task execution history tracking
• Add input validation and sanitization
• Create comprehensive error handling

Acceptance Criteria

• All endpoints return proper HTTP status codes
• Input validation prevents invalid task creation
• Pagination works with configurable page sizes
• Filtering by status and date ranges functional
• Authorization ensures users only access their tasks
• Error responses include helpful error messages
• API rate limiting implemented per user

Definition of Done

• All CRUD endpoints implemented and tested
• Comprehensive input validation in place
• Pagination and filtering working correctly
• Unit and integration tests covering happy/error paths
• OpenAPI documentation generated and accurate
• Performance tested with 1000+ tasks per user

API Endpoints

Task Management

POST   /api/v1/tasks              # Create new task
GET    /api/v1/tasks              # List user's tasks
GET    /api/v1/tasks/{id}         # Get task details
PUT    /api/v1/tasks/{id}         # Update task
DELETE /api/v1/tasks/{id}         # Delete task
POST   /api/v1/tasks/{id}/execute # Execute task

Task Execution Management

GET    /api/v1/tasks/{id}/executions        # Get execution history
GET    /api/v1/tasks/{id}/executions/{exec_id} # Get execution details
DELETE /api/v1/tasks/{id}/executions/{exec_id} # Cancel execution

Request/Response Examples

Create Task

POST /api/v1/tasks
{
  "name": "Data Processing Script",
  "description": "Process CSV data and generate report",
  "script_content": "import pandas as pd\\nprint('Processing...')",
  "script_type": "python",
  "timeout_seconds": 30,
  "metadata": {
    "tags": ["data", "processing"],
    "priority": "high"
  }
}

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Data Processing Script",
  "status": "pending",
  "created_at": "2025-07-03T10:00:00Z",
  "user_id": "user-uuid"
}

List Tasks with Filtering

GET /api/v1/tasks?status=running&page=1&limit=20&sort=created_at&order=desc

Validation Rules

• Task name: 1-255 characters, required
• Script content: Max 1MB, required
• Script type: Must be "python" or "bash"
• Timeout: 1-3600 seconds
• Priority: 0-10 integer

Related Epic

Contributes to Epic #1: Core API Infrastructure