docs: Update CHANGELOG and README for deployment models and troubleshooting
- Added multi-platform deployment architecture details (Web App, PWA, DApp) to README.md. - Included comprehensive troubleshooting guides and fix scripts in README.md. - Enhanced CHANGELOG.md with new features, fixes, and improvements, including TypeScript error resolutions and updated documentation structure. - Revised development setup instructions in DEV_SETUP.md to reflect changes in script usage and environment variable setup.
This commit is contained in:
defiQUG
343
docs/API_USAGE_EXAMPLES.md
Normal file
343
docs/API_USAGE_EXAMPLES.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# API Usage Examples
|
||||
|
||||
This document provides practical examples for using the Orchestrator API.
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
All API requests require authentication via API key in the header:
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" \
|
||||
http://localhost:8080/api/plans
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plan Management
|
||||
|
||||
### Create a Plan
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/plans \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"creator": "user@example.com",
|
||||
"steps": [
|
||||
{
|
||||
"type": "borrow",
|
||||
"asset": "USDC",
|
||||
"amount": 1000,
|
||||
"from": "aave"
|
||||
},
|
||||
{
|
||||
"type": "swap",
|
||||
"asset": "USDC",
|
||||
"amount": 1000,
|
||||
"from": "USDC",
|
||||
"to": "ETH"
|
||||
}
|
||||
],
|
||||
"maxRecursion": 3,
|
||||
"maxLTV": 0.6
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"plan_id": "plan-12345",
|
||||
"plan_hash": "0xabc123...",
|
||||
"created_at": "2025-01-15T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Plan
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/plans/plan-12345 \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Add Signature
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/plans/plan-12345/signature \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"signature": "0xdef456...",
|
||||
"messageHash": "0x789abc...",
|
||||
"signerAddress": "0x1234567890abcdef..."
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Execute Plan
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/plans/plan-12345/execute \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"executionId": "exec-67890",
|
||||
"status": "pending",
|
||||
"startedAt": "2025-01-15T10:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Execution Status
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/plans/plan-12345/status?executionId=exec-67890 \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Stream Execution Status (SSE)
|
||||
|
||||
```bash
|
||||
curl -N http://localhost:8080/api/plans/plan-12345/status/stream \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Abort Execution
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/plans/plan-12345/abort?executionId=exec-67890 \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compliance
|
||||
|
||||
### Check Compliance Status
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/compliance/status \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"lei": "5493000JXH2RCDW0KV24",
|
||||
"did": "did:web:example.com:user123",
|
||||
"kyc": {
|
||||
"level": 2,
|
||||
"verified": true,
|
||||
"expiresAt": "2026-01-15T00:00:00Z"
|
||||
},
|
||||
"aml": {
|
||||
"passed": true,
|
||||
"lastCheck": "2025-01-15T09:00:00Z",
|
||||
"riskLevel": "low"
|
||||
},
|
||||
"valid": true
|
||||
}
|
||||
```
|
||||
|
||||
### Validate Plan Compliance
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/compliance/check \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"steps": [
|
||||
{"type": "pay", "amount": 1000}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Simulation
|
||||
|
||||
### Simulate Plan Execution
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/plans/plan-12345/simulate \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"includeGasEstimate": true,
|
||||
"includeSlippageAnalysis": true,
|
||||
"includeLiquidityCheck": true
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"gasEstimate": 250000,
|
||||
"slippage": 0.5,
|
||||
"liquidityCheck": true,
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adapters
|
||||
|
||||
### List Available Adapters
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/adapters \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"adapters": [
|
||||
{
|
||||
"id": "uniswap-v3",
|
||||
"name": "Uniswap V3",
|
||||
"type": "swap",
|
||||
"whitelisted": true,
|
||||
"status": "active"
|
||||
},
|
||||
{
|
||||
"id": "aave-v3",
|
||||
"name": "Aave V3",
|
||||
"type": "borrow",
|
||||
"whitelisted": true,
|
||||
"status": "active"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health & Monitoring
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
### Metrics (Prometheus)
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/metrics
|
||||
```
|
||||
|
||||
### Liveness Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/live
|
||||
```
|
||||
|
||||
### Readiness Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/ready
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
All errors follow this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "VALIDATION_ERROR",
|
||||
"message": "Invalid plan structure",
|
||||
"details": {
|
||||
"field": "steps",
|
||||
"issue": "Steps array cannot be empty"
|
||||
},
|
||||
"requestId": "req-12345"
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Types
|
||||
|
||||
- `VALIDATION_ERROR` (400): Invalid input data
|
||||
- `NOT_FOUND_ERROR` (404): Resource not found
|
||||
- `AUTHENTICATION_ERROR` (401): Missing or invalid API key
|
||||
- `EXTERNAL_SERVICE_ERROR` (502): External service failure
|
||||
- `SYSTEM_ERROR` (500): Internal server error
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
API requests are rate-limited:
|
||||
- **Default**: 100 requests per minute per API key
|
||||
- **Burst**: 20 requests per second
|
||||
|
||||
Rate limit headers:
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1642248000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhooks
|
||||
|
||||
Register a webhook for plan status updates:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/webhooks \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"url": "https://your-app.com/webhooks",
|
||||
"secret": "webhook-secret",
|
||||
"events": ["plan.status", "plan.executed"]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Example: Full Flow
|
||||
|
||||
```bash
|
||||
# 1. Create plan
|
||||
PLAN_ID=$(curl -X POST http://localhost:8080/api/plans \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"creator":"user@example.com","steps":[...]}' \
|
||||
| jq -r '.plan_id')
|
||||
|
||||
# 2. Add signature
|
||||
curl -X POST http://localhost:8080/api/plans/$PLAN_ID/signature \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"signature":"0x...","messageHash":"0x...","signerAddress":"0x..."}'
|
||||
|
||||
# 3. Execute
|
||||
EXEC_ID=$(curl -X POST http://localhost:8080/api/plans/$PLAN_ID/execute \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
| jq -r '.executionId')
|
||||
|
||||
# 4. Monitor status
|
||||
curl -N http://localhost:8080/api/plans/$PLAN_ID/status/stream \
|
||||
-H "X-API-Key: your-api-key"
|
||||
|
||||
# 5. Get receipts
|
||||
curl http://localhost:8080/api/receipts/$PLAN_ID \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-15
|
||||
|
||||
Reference in New Issue
Block a user