Reference

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:

1
GET /api/v1/openapi.json

Or YAML format:

1
GET /api/v1/openapi.yaml

Best Practices

1. Use Idempotency Keys

For critical operations, use idempotency keys to prevent duplicate executions:

1
POST /api/v1/workflows/execute
2
Authorization: Bearer <token>
3
Idempotency-Key: unique-key-123
4
Content-Type: application/json
5
6
{...}

2. Handle Rate Limits

Implement exponential backoff when rate limited:

1
async 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:

1
POST /api/v1/workflows/execute
2
Content-Type: application/json
3
4
{
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:

1
use reqwest::Client;
2
use std::time::Duration;
3
4
let client = Client::builder()
5
.timeout(Duration::from_secs(30))
6
.build()?;

5. Use Compression

Enable compression to reduce bandwidth:

1
GET /api/v1/executions
2
Accept-Encoding: gzip, deflate, br

SDK 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. Authenticate
2
curl -X POST http://localhost:8080/api/v1/auth/login \
3
-H "Content-Type: application/json" \
4
-d '{"email":"user@example.com","password":"pass"}'
5
6
# 2. Start workflow
7
curl -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
}'
15
16
# 3. Check status
17
curl http://localhost:8080/api/v1/executions/exec_abc123/status \
18
-H "Authorization: Bearer $TOKEN"
19
20
# 4. Get result
21
curl http://localhost:8080/api/v1/executions/exec_abc123/result \
22
-H "Authorization: Bearer $TOKEN"

Streaming Logs with curl

1
curl -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 tasks
2
for i in {1..10}; do
3
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}}"
7
done

Additional Resources


Next Steps