Skip to content

API Reference

REST API

Process Definitions

List Process Definitions

GET /processes

Response: 

{
  "data": {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Order Processing",
        "version": 1,
        "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
        "created_at": "2025-02-03T12:00:00Z",
        "updated_at": "2025-02-03T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 1,
    "totalPages": 1
  }
}

Get Process Definition

GET /processes/{process_id}

Response: 

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Order Processing",
    "version": 1,
    "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "created_at": "2025-02-03T12:00:00Z",
    "updated_at": "2025-02-03T12:00:00Z"
  }
}

Create Process Definition

POST /processes
Content-Type: application/json

{
  "name": "Order Processing",
  "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
  "version": 1  // Optional, defaults to 1
}

Response: 

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Order Processing",
    "version": 1,
    "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "created_at": "2025-02-03T12:00:00Z",
    "updated_at": "2025-02-03T12:00:00Z"
  }
}

Update Process Definition

PUT /processes/{process_id}
Content-Type: application/json

{
  "name": "Updated Order Process",  // Optional
  "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",  // Optional
  "version": 2  // Optional, auto-increments if not specified
}

Response: 

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Updated Order Process",
    "version": 2,
    "bpmn_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "created_at": "2025-02-03T12:00:00Z",
    "updated_at": "2025-02-03T12:01:00Z"
  }
}

Delete Process Definition

DELETE /processes/{process_id}

Response: 

{
  "message": "Process deleted successfully"
}

Error Handling

All error responses follow this format: 

{
  "detail": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "context": {
    "additional": "error context"
  }
}

Common error scenarios: - 404: Process not found - 500: Internal server error (with error details) - 503: Service unavailable (connection issues)

Connection failures return 503 Service Unavailable with specific error codes:

{
  "detail": "Database connection failed: connection refused",
  "code": "DB_CONNECTION_ERROR",
  "context": {
    "service": "database",
    "attempt": 3,
    "max_attempts": 3
  }
}

Common connection error codes: - DB_CONNECTION_ERROR: Database connection issues - REDIS_CONNECTION_ERROR: Redis connection issues - RABBITMQ_CONNECTION_ERROR: RabbitMQ connection issues

The system will automatically attempt to reconnect based on configuration: 

{
  "detail": "Service temporarily unavailable, retrying connection",
  "code": "SERVICE_RECONNECTING",
  "context": {
    "service": "database",
    "attempt": 2,
    "max_attempts": 3,
    "retry_delay": 5
  }
}

Data Models

ProcessDefinitionCreate

{
  name: string;          // Process definition name
  bpmn_xml: string;      // BPMN 2.0 XML content
  version?: number;      // Optional version number (defaults to 1)
}

ProcessDefinitionUpdate

{
  name?: string;         // Optional new name
  bpmn_xml?: string;    // Optional new BPMN XML
  version?: number;     // Optional new version
}

ProcessDefinitionResponse

{
  id: UUID;             // Unique identifier
  name: string;         // Process name
  version: number;      // Version number
  bpmn_xml: string;     // BPMN XML content
  created_at: string;   // Creation timestamp
  updated_at: string;   // Last update timestamp
}

PaginatedResponse

{
  items: T[];           // Array of items
  total: number;        // Total number of items
  page: number;         // Current page number
  pageSize: number;     // Items per page
  totalPages: number;   // Total number of pages
}

API Response Wrapper

All successful responses are wrapped in a data object: 

{
  data: T;  // Response data of type T
}

Connection Management

Connection States

The API provides connection state information through headers: 

X-Service-Status: connected
X-Connection-Attempts: 1
X-Last-Connected: 2025-02-03T12:00:00Z

Health Check Endpoint

GET /health

Response: 

{
  "status": "healthy",
  "services": {
    "database": {
      "status": "connected",
      "last_connected": "2025-02-03T12:00:00Z"
    },
    "redis": {
      "status": "connected",
      "last_connected": "2025-02-03T12:00:00Z"
    },
    "rabbitmq": {
      "status": "connected",
      "last_connected": "2025-02-03T12:00:00Z"
    }
  }
}

Best Practices

  1. Connection Management
  2. Monitor connection states via health endpoint
  3. Handle 503 errors with appropriate retry logic
  4. Implement circuit breaker for failing services

  5. Log connection-related errors for monitoring

  6. Version Management

  7. Process definitions are versioned automatically
  8. Version increments on updates unless specified

  9. Keep track of version history

  10. Error Handling

  11. Check for 404 when accessing specific processes
  12. Handle 500 errors with proper error messages

  13. Use try-catch blocks for error handling

  14. BPMN XML

  15. Validate BPMN XML before sending
  16. Use proper XML escaping

  17. Include all required BPMN elements

  18. Pagination

  19. Current implementation returns all items
  20. Future enhancement: add page and pageSize query parameters
  21. Handle empty result sets appropriately

Example Usage

Using fetch: 

// List processes
const response = await fetch('/processes');
const { data } = await response.json();
const processes = data.items;

// Create process
const newProcess = await fetch('/processes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'New Process',
    bpmn_xml: '<?xml version="1.0" encoding="UTF-8"?>...',
  }),
});

// Update process
const updatedProcess = await fetch(`/processes/${processId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Updated Process',
  }),
});

// Delete process
await fetch(`/processes/${processId}`, {
  method: 'DELETE',
});

Using Python requests: ```python import requests

List processes

response = requests.get('/processes') processes = response.json()['data']['items']

Create process

response = requests.post('/processes', json={ 'name': 'New Process', 'bpmn_xml': '<?xml version="1.0" encoding="UTF-8"?>...', }) new_process = response.json()['data']

Update process

response = requests.put(f'/processes/{process_id}', json={ 'name': 'Updated Process', }) updated_process = response.json()['data']

Delete process

response = requests.delete(f'/processes/{process_id}')