Best Practices & Examples
API Documentation
Interactive Documentation
Orcher provides interactive API documentation powered by OpenAPI:
- Swagger UI:
http://localhost:8080/api/docs/swagger - ReDoc:
http://localhost:8080/api/docs/redoc - RapiDoc:
http://localhost:8080/api/docs/rapidoc - Scalar:
http://localhost:8080/api/docs/scalar
OpenAPI Specification
Download the OpenAPI spec:
1GET /api/v1/openapi.jsonOr YAML format:
1GET /api/v1/openapi.yamlBest Practices
1. Use Idempotency Keys
For critical operations, use idempotency keys to prevent duplicate executions:
1POST /api/v1/workflows/execute2Authorization: Bearer <token>3Idempotency-Key: unique-key-1234Content-Type: application/json56{...}2. Handle Rate Limits
Implement exponential backoff when rate limited:
1async fn retry_with_backoff(request: Request) -> Result<Response> {2 let mut delay = 1;3 loop {4 match send_request(&request).await {5 Ok(response) => return Ok(response),6 Err(e) if e.is_rate_limited() => {7 tokio::time::sleep(Duration::from_secs(delay)).await;8 delay *= 2;9 }10 Err(e) => return Err(e),11 }12 }13}3. Use Webhooks for Long Operations
Instead of polling, use webhooks for long-running workflows:
1POST /api/v1/workflows/execute2Content-Type: application/json34{5 "workflow_type": "data_processing",6 "webhook_url": "https://yourapp.com/webhooks/workflow",7 "input": {...}8}4. Implement Timeouts
Set appropriate timeouts for your requests:
1use reqwest::Client;2use std::time::Duration;34let client = Client::builder()5 .timeout(Duration::from_secs(30))6 .build()?;5. Use Compression
Enable compression to reduce bandwidth:
1GET /api/v1/executions2Accept-Encoding: gzip, deflate, brSDK Support
While you can use the REST API directly, Orcher provides official SDKs that connect via gRPC for optimal performance:
- Rust SDK -- Type-safe Rust client with compile-time guarantees
- TypeScript SDK -- Node.js with decorators and dependency injection
- Python SDK -- Python 3.10+ with async/await and decorators
Examples
Complete Workflow Execution Flow
1# 1. Authenticate2curl -X POST http://localhost:8080/api/v1/auth/login \3 -H "Content-Type: application/json" \4 -d '{"email":"user@example.com","password":"pass"}'56# 2. Start workflow7curl -X POST http://localhost:8080/api/v1/workflows/execute \8 -H "Authorization: Bearer $TOKEN" \9 -H "Content-Type: application/json" \10 -d '{11 "workflow_type": "order_processing",12 "workflow_id": "order-12345",13 "input": {"order_id": "12345"}14 }'1516# 3. Check status17curl http://localhost:8080/api/v1/executions/exec_abc123/status \18 -H "Authorization: Bearer $TOKEN"1920# 4. Get result21curl http://localhost:8080/api/v1/executions/exec_abc123/result \22 -H "Authorization: Bearer $TOKEN"Streaming Logs with curl
1curl -N http://localhost:8080/api/v1/executions/exec_abc123/logs/stream \2 -H "Authorization: Bearer $TOKEN" \3 -H "Accept: text/event-stream"Batch Operations
1# Submit multiple tasks2for i in {1..10}; do3 curl -X POST http://localhost:8080/api/v1/tasks \4 -H "Authorization: Bearer $TOKEN" \5 -H "Content-Type: application/json" \6 -d "{\"task_type\":\"process_item\",\"input\":{\"id\":$i}}"7doneAdditional Resources
- CLI Reference -- Command-line interface for workflow management
- Platform Engineers Guide -- Deployment, monitoring, and operations
Next Steps
- API Overview -- Authentication and getting started
- Workflow Endpoints -- Execute, monitor, and manage workflow executions
- Task Endpoints -- Submit and track tasks
- Errors & Limits -- Error handling and rate limiting