Background Tasks API
This section details the APIs available for managing and interacting with background tasks within the platform. Background tasks allow for asynchronous operations, ensuring that your application remains responsive while performing potentially time-consuming operations.
Task Management Endpoints
POST /tasks
Creates a new background task.
Request Body:
{
"name": "string",
"description": "string",
"payload": "object",
"schedule": {
"type": "string (e.g., 'immediate', 'cron', 'delayed')",
"details": "object"
}
}
Response:
{
"taskId": "uuid",
"status": "pending",
"createdAt": "timestamp"
}
GET /tasks/{taskId}
Retrieves the status and details of a specific background task.
Parameters:
taskId(string, required): The unique identifier of the task.
Response:
{
"taskId": "uuid",
"name": "string",
"description": "string",
"status": "string (e.g., 'pending', 'running', 'completed', 'failed')",
"progress": "integer (0-100)",
"result": "object (if completed)",
"error": "string (if failed)",
"createdAt": "timestamp",
"startedAt": "timestamp (optional)",
"completedAt": "timestamp (optional)"
}
GET /tasks
Retrieves a list of all background tasks associated with the authenticated user or application.
Query Parameters:
status(string, optional): Filter tasks by status (e.g., 'completed', 'failed').limit(integer, optional): Maximum number of tasks to return.offset(integer, optional): Number of tasks to skip.
Response:
{
"tasks": [
{
"taskId": "uuid",
"name": "string",
"status": "string",
"createdAt": "timestamp"
}
// ... more tasks
],
"total": "integer"
}
DELETE /tasks/{taskId}
Cancels or deletes a background task. The behavior depends on the task's current state.
Parameters:
taskId(string, required): The unique identifier of the task to cancel/delete.
Response:
{
"message": "Task {taskId} cancelled successfully."
}
Task Scheduling Options
The schedule object in the POST /tasks request allows for flexible scheduling:
- Immediate: Execute the task as soon as possible.
"schedule": { "type": "immediate" } - Delayed: Execute the task after a specified delay.
"schedule": { "type": "delayed", "details": { "delayInSeconds": 300 } } - Cron: Execute the task based on a cron expression.
"schedule": { "type": "cron", "details": { "expression": "0 0 * * *" } }Supported cron format: Standard Unix cron syntax.
Error Handling
Failed tasks will have their status set to failed, and an error field will be populated with details about the failure. It is recommended to implement robust error handling and retry mechanisms in your application.