Operations

Operations represent asynchronous actions in the Onvera platform. Most API endpoints return operations that you must poll to track progress.

Operation Lifecycle

Operations go through the following lifecycle:

1. Created - Operation is created when you perform an action
2. Queued - Operation is queued and waiting to start
3. Running - Operation is currently executing
4. Terminal State - Operation completes (succeeded, failed, or canceled)

Operation Statuses

Terminal States

These states indicate the operation will not change:

• succeeded - Operation completed successfully
• failed - Operation failed
• canceled - Operation was canceled

Non-Terminal States

These states indicate the operation is still in progress:

• queued - Waiting to start
• running - Currently executing

Polling Patterns

Since operations are asynchronous, you need to poll for status updates.

Basic Polling

Poll the operation endpoint until it reaches a terminal state:

# Get operation status
curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001

Polling Interval

Recommended: Poll every 2-5 seconds. Don't poll too frequently to avoid rate limits.

Polling Example

#!/bin/bash
 
OPERATION_ID="op_660e8400-e29b-41d4-a716-446655440001"
API_KEY="onv_sk_live_..."
 
while true; do
  RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" \
    https://api.onvera.io/api/v1/operations/$OPERATION_ID)
  
  STATUS=$(echo $RESPONSE | jq -r '.data.status')
  
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "canceled" ]; then
    echo "Operation completed with status: $STATUS"
    break
  fi
  
  sleep 2
done

Operation Endpoints

List Operations

GET /api/v1/operations

Query Parameters:

• status - Filter by status (queued, running, succeeded, failed, canceled)
• type - Filter by operation type (e.g., deployment.create)
• resource_id - Filter by resource ID
• page - Page number (default: 1)
• per_page - Items per page (default: 50, max: 100)

Example:

curl -H "X-API-Key: onv_sk_live_..." \
  "https://api.onvera.io/api/v1/operations?status=running&type=deployment.create"

Response:

{
  "data": {
    "items": [
      {
        "id": "op_660e8400-e29b-41d4-a716-446655440001",
        "type": "deployment.create",
        "status": "running",
        "progress": {
          "phase": "provisioning_db",
          "message": "Provisioning database"
        },
        "resource": {
          "type": "deployment",
          "id": "dep_550e8400-e29b-41d4-a716-446655440000"
        },
        "requested_at": "2024-01-20T12:00:00Z",
        "started_at": "2024-01-20T12:00:15Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 1,
      "pages": 1
    }
  }
}

Get Operation

GET /api/v1/operations/{operation_id}

Example:

curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001

Response:

{
  "data": {
    "id": "op_660e8400-e29b-41d4-a716-446655440001",
    "type": "deployment.create",
    "status": "succeeded",
    "progress": {
      "phase": "ready",
      "message": "Deployment ready"
    },
    "resource": {
      "type": "deployment",
      "id": "dep_550e8400-e29b-41d4-a716-446655440000"
    },
    "requested_at": "2024-01-20T12:00:00Z",
    "started_at": "2024-01-20T12:00:15Z",
    "ended_at": "2024-01-20T12:06:15Z"
  }
}

Operation Types

Common operation types:

• deployment.create - Creating a deployment
• deployment.destroy - Destroying a deployment
• dag_sync.trigger - Syncing DAGs from GitHub
• app_user.provision - Provisioning a user in an application

Operation Progress

Operations include progress information:

• phase - Current phase (e.g., provisioning_db, provisioning_infrastructure)
• message - Human-readable message describing current state

Example:

{
  "progress": {
    "phase": "provisioning_db",
    "message": "Provisioning database"
  }
}

Best Practices

1. Always store the operation_id when creating resources
2. Poll until terminal state - Don't assume immediate completion
3. Handle failures gracefully - Check error messages
4. Respect rate limits - Don't poll too frequently (2-5 seconds recommended)
5. Use exponential backoff for retries
6. Set timeouts - Don't poll indefinitely

Related Concepts

• Concepts: Operations - Learn about operations
• Deployments - Deployment API reference