72d16929ca
Major refactoring to hexagonal (ports & adapters) architecture: - Add service layer (apikey_service, project_service) for business logic - Add webhook system with dispatcher and delivery tracking - Add command queue with priority-based processing - Add rate limiting with sliding window algorithm - Add audit logging for command execution - Add OpenTelemetry integration (traces, metrics, spans) - Add circuit breaker for fault tolerance - Add cached repository wrapper for performance - Add comprehensive validation package - Add Kubernetes client integration for pod management - Add database migrations (allowed_ips, audit_log, rate_limiting, queue, webhooks) - Add network policy and PodDisruptionBudget for k8s - Remove legacy executor and projects/registry packages - Untrack secrets.yaml (now managed via envault) - Add coverage.out to .gitignore - Add e2e test infrastructure with docker-compose - Add comprehensive documentation (API, architecture, operations, plans) - Add golangci-lint config and pre-commit hook Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
146 lines
2.9 KiB
Markdown
146 lines
2.9 KiB
Markdown
# rdev API Documentation
|
|
|
|
rdev provides a REST API for remote development environments with SSE streaming support.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Get an API Key
|
|
|
|
Contact your administrator to get an API key, or create one if you have admin access:
|
|
|
|
```bash
|
|
curl -X POST https://rdev.example.com/keys \
|
|
-H "X-API-Key: your-admin-key" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "my-key",
|
|
"scopes": ["projects:read", "projects:execute"]
|
|
}'
|
|
```
|
|
|
|
### 2. List Projects
|
|
|
|
```bash
|
|
curl https://rdev.example.com/projects \
|
|
-H "X-API-Key: your-key"
|
|
```
|
|
|
|
### 3. Execute a Command
|
|
|
|
```bash
|
|
curl -X POST https://rdev.example.com/projects/my-project/shell \
|
|
-H "X-API-Key: your-key" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"command": "ls -la"}'
|
|
```
|
|
|
|
### 4. Stream Output
|
|
|
|
```bash
|
|
curl -N https://rdev.example.com/projects/my-project/events?stream_id=cmd-001 \
|
|
-H "X-API-Key: your-key"
|
|
```
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://rdev.example.com
|
|
```
|
|
|
|
## Authentication
|
|
|
|
See [authentication.md](authentication.md) for details.
|
|
|
|
All requests (except `/health`, `/ready`, `/metrics`) require authentication.
|
|
|
|
**Header:**
|
|
```
|
|
X-API-Key: rdev_xxxx...
|
|
```
|
|
|
|
Or:
|
|
```
|
|
Authorization: Bearer rdev_xxxx...
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| GET | `/projects` | List all projects |
|
|
| GET | `/projects/{id}` | Get project details |
|
|
| POST | `/projects/{id}/claude` | Run Claude command |
|
|
| POST | `/projects/{id}/shell` | Run shell command |
|
|
| POST | `/projects/{id}/git` | Run git command |
|
|
| GET | `/projects/{id}/events` | SSE event stream |
|
|
| GET | `/keys` | List API keys |
|
|
| POST | `/keys` | Create API key |
|
|
| DELETE | `/keys/{id}` | Revoke API key |
|
|
| GET | `/health` | Liveness check |
|
|
| GET | `/ready` | Readiness check |
|
|
| GET | `/metrics` | Prometheus metrics |
|
|
|
|
## Response Format
|
|
|
|
All responses follow this format:
|
|
|
|
### Success
|
|
|
|
```json
|
|
{
|
|
"data": { ... },
|
|
"meta": {
|
|
"request_id": "req-abc123",
|
|
"timestamp": "2024-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "NOT_FOUND",
|
|
"message": "Project not found: my-project"
|
|
},
|
|
"meta": {
|
|
"request_id": "req-abc123",
|
|
"timestamp": "2024-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
| Code | HTTP Status | Description |
|
|
|------|-------------|-------------|
|
|
| `BAD_REQUEST` | 400 | Invalid request body or parameters |
|
|
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
|
|
| `FORBIDDEN` | 403 | Insufficient permissions |
|
|
| `NOT_FOUND` | 404 | Resource not found |
|
|
| `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |
|
|
| `INTERNAL_ERROR` | 500 | Server error |
|
|
|
|
## Rate Limiting
|
|
|
|
Requests are rate limited per API key:
|
|
|
|
| Limit Type | Default |
|
|
|------------|---------|
|
|
| Requests/second | 10 |
|
|
| Concurrent commands | 5 |
|
|
|
|
Headers:
|
|
```
|
|
X-RateLimit-Limit: 10
|
|
X-RateLimit-Remaining: 7
|
|
X-RateLimit-Reset: 1642089600
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Authentication Guide](authentication.md)
|
|
- [SSE Streaming Examples](sse-examples.md)
|
|
- [Error Handling](errors.md)
|