release orchestrator pivot, architecture and planning
This commit is contained in:
299
docs/modules/release-orchestrator/api/overview.md
Normal file
299
docs/modules/release-orchestrator/api/overview.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# API Overview
|
||||
|
||||
**Version**: v1
|
||||
**Base Path**: `/api/v1`
|
||||
|
||||
## Design Principles
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|----------------|
|
||||
| **RESTful** | Resource-oriented URLs, standard HTTP methods |
|
||||
| **Versioned** | `/api/v1/...` prefix; breaking changes require version bump |
|
||||
| **Consistent** | Standard response envelope, error format, pagination |
|
||||
| **Authenticated** | OAuth 2.0 Bearer tokens via Authority module |
|
||||
| **Tenant-scoped** | Tenant ID from token; all operations scoped to tenant |
|
||||
| **Audited** | All mutating operations logged with user/timestamp |
|
||||
|
||||
## Authentication
|
||||
|
||||
All API requests require a valid JWT Bearer token:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Tokens are issued by the Authority module and contain:
|
||||
- `user_id`: User identifier
|
||||
- `tenant_id`: Tenant scope
|
||||
- `roles`: User roles
|
||||
- `permissions`: Specific permissions
|
||||
|
||||
## Standard Response Envelope
|
||||
|
||||
### Success Response
|
||||
|
||||
```typescript
|
||||
interface ApiResponse<T> {
|
||||
success: true;
|
||||
data: T;
|
||||
meta?: {
|
||||
pagination?: PaginationMeta;
|
||||
requestId: string;
|
||||
timestamp: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response
|
||||
|
||||
```typescript
|
||||
interface ApiErrorResponse {
|
||||
success: false;
|
||||
error: {
|
||||
code: string; // e.g., "PROMOTION_BLOCKED"
|
||||
message: string; // Human-readable message
|
||||
details?: object; // Additional context
|
||||
validationErrors?: ValidationError[];
|
||||
};
|
||||
meta: {
|
||||
requestId: string;
|
||||
timestamp: string;
|
||||
};
|
||||
}
|
||||
|
||||
interface ValidationError {
|
||||
field: string;
|
||||
message: string;
|
||||
code: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
```typescript
|
||||
interface PaginationMeta {
|
||||
page: number;
|
||||
pageSize: number;
|
||||
totalItems: number;
|
||||
totalPages: number;
|
||||
hasNext: boolean;
|
||||
hasPrevious: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
## HTTP Status Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `200` | Success |
|
||||
| `201` | Created |
|
||||
| `204` | No Content |
|
||||
| `400` | Bad Request - validation error |
|
||||
| `401` | Unauthorized - invalid/missing token |
|
||||
| `403` | Forbidden - insufficient permissions |
|
||||
| `404` | Not Found |
|
||||
| `409` | Conflict - resource state conflict |
|
||||
| `422` | Unprocessable Entity - business rule violation |
|
||||
| `429` | Too Many Requests - rate limited |
|
||||
| `500` | Internal Server Error |
|
||||
|
||||
## Common Query Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `page` | integer | Page number (1-indexed) |
|
||||
| `pageSize` | integer | Items per page (max 100) |
|
||||
| `sort` | string | Sort field (prefix `-` for descending) |
|
||||
| `filter` | string | JSON filter expression |
|
||||
|
||||
## API Modules
|
||||
|
||||
### Integration Hub (INTHUB)
|
||||
|
||||
```
|
||||
GET /api/v1/integration-types
|
||||
GET /api/v1/integration-types/{typeId}
|
||||
POST /api/v1/integrations
|
||||
GET /api/v1/integrations
|
||||
GET /api/v1/integrations/{id}
|
||||
PUT /api/v1/integrations/{id}
|
||||
DELETE /api/v1/integrations/{id}
|
||||
POST /api/v1/integrations/{id}/test
|
||||
POST /api/v1/integrations/{id}/discover
|
||||
GET /api/v1/integrations/{id}/health
|
||||
```
|
||||
|
||||
### Environment & Inventory (ENVMGR)
|
||||
|
||||
```
|
||||
POST /api/v1/environments
|
||||
GET /api/v1/environments
|
||||
GET /api/v1/environments/{id}
|
||||
PUT /api/v1/environments/{id}
|
||||
DELETE /api/v1/environments/{id}
|
||||
POST /api/v1/environments/{envId}/freeze-windows
|
||||
GET /api/v1/environments/{envId}/freeze-windows
|
||||
DELETE /api/v1/environments/{envId}/freeze-windows/{windowId}
|
||||
POST /api/v1/targets
|
||||
GET /api/v1/targets
|
||||
GET /api/v1/targets/{id}
|
||||
PUT /api/v1/targets/{id}
|
||||
DELETE /api/v1/targets/{id}
|
||||
POST /api/v1/targets/{id}/health-check
|
||||
GET /api/v1/targets/{id}/sticker
|
||||
GET /api/v1/targets/{id}/drift
|
||||
POST /api/v1/agents/register
|
||||
GET /api/v1/agents
|
||||
GET /api/v1/agents/{id}
|
||||
PUT /api/v1/agents/{id}
|
||||
DELETE /api/v1/agents/{id}
|
||||
POST /api/v1/agents/{id}/heartbeat
|
||||
```
|
||||
|
||||
### Release Management (RELMAN)
|
||||
|
||||
```
|
||||
POST /api/v1/components
|
||||
GET /api/v1/components
|
||||
GET /api/v1/components/{id}
|
||||
PUT /api/v1/components/{id}
|
||||
DELETE /api/v1/components/{id}
|
||||
POST /api/v1/components/{id}/sync-versions
|
||||
GET /api/v1/components/{id}/versions
|
||||
POST /api/v1/releases
|
||||
GET /api/v1/releases
|
||||
GET /api/v1/releases/{id}
|
||||
PUT /api/v1/releases/{id}
|
||||
DELETE /api/v1/releases/{id}
|
||||
GET /api/v1/releases/{id}/state
|
||||
POST /api/v1/releases/{id}/deprecate
|
||||
GET /api/v1/releases/{id}/compare/{otherId}
|
||||
POST /api/v1/releases/from-latest
|
||||
```
|
||||
|
||||
### Workflow Engine (WORKFL)
|
||||
|
||||
```
|
||||
POST /api/v1/workflow-templates
|
||||
GET /api/v1/workflow-templates
|
||||
GET /api/v1/workflow-templates/{id}
|
||||
PUT /api/v1/workflow-templates/{id}
|
||||
DELETE /api/v1/workflow-templates/{id}
|
||||
POST /api/v1/workflow-templates/{id}/validate
|
||||
GET /api/v1/step-types
|
||||
GET /api/v1/step-types/{type}
|
||||
POST /api/v1/workflow-runs
|
||||
GET /api/v1/workflow-runs
|
||||
GET /api/v1/workflow-runs/{id}
|
||||
POST /api/v1/workflow-runs/{id}/pause
|
||||
POST /api/v1/workflow-runs/{id}/resume
|
||||
POST /api/v1/workflow-runs/{id}/cancel
|
||||
GET /api/v1/workflow-runs/{id}/steps
|
||||
GET /api/v1/workflow-runs/{id}/steps/{nodeId}
|
||||
GET /api/v1/workflow-runs/{id}/steps/{nodeId}/logs
|
||||
GET /api/v1/workflow-runs/{id}/steps/{nodeId}/artifacts
|
||||
```
|
||||
|
||||
### Promotion & Approval (PROMOT)
|
||||
|
||||
```
|
||||
POST /api/v1/promotions
|
||||
GET /api/v1/promotions
|
||||
GET /api/v1/promotions/{id}
|
||||
POST /api/v1/promotions/{id}/approve
|
||||
POST /api/v1/promotions/{id}/reject
|
||||
POST /api/v1/promotions/{id}/cancel
|
||||
GET /api/v1/promotions/{id}/decision
|
||||
GET /api/v1/promotions/{id}/approvals
|
||||
GET /api/v1/promotions/{id}/evidence
|
||||
POST /api/v1/promotions/preview-gates
|
||||
POST /api/v1/approval-policies
|
||||
GET /api/v1/approval-policies
|
||||
GET /api/v1/my/pending-approvals
|
||||
```
|
||||
|
||||
### Deployment (DEPLOY)
|
||||
|
||||
```
|
||||
GET /api/v1/deployment-jobs
|
||||
GET /api/v1/deployment-jobs/{id}
|
||||
GET /api/v1/deployment-jobs/{id}/tasks
|
||||
GET /api/v1/deployment-jobs/{id}/tasks/{taskId}
|
||||
GET /api/v1/deployment-jobs/{id}/tasks/{taskId}/logs
|
||||
GET /api/v1/deployment-jobs/{id}/artifacts
|
||||
GET /api/v1/deployment-jobs/{id}/artifacts/{artifactId}
|
||||
POST /api/v1/rollbacks
|
||||
GET /api/v1/rollbacks
|
||||
```
|
||||
|
||||
### Progressive Delivery (PROGDL)
|
||||
|
||||
```
|
||||
POST /api/v1/ab-releases
|
||||
GET /api/v1/ab-releases
|
||||
GET /api/v1/ab-releases/{id}
|
||||
POST /api/v1/ab-releases/{id}/start
|
||||
POST /api/v1/ab-releases/{id}/advance
|
||||
POST /api/v1/ab-releases/{id}/promote
|
||||
POST /api/v1/ab-releases/{id}/rollback
|
||||
GET /api/v1/ab-releases/{id}/traffic
|
||||
GET /api/v1/ab-releases/{id}/health
|
||||
GET /api/v1/rollout-strategies
|
||||
```
|
||||
|
||||
### Release Evidence (RELEVI)
|
||||
|
||||
```
|
||||
GET /api/v1/evidence-packets
|
||||
GET /api/v1/evidence-packets/{id}
|
||||
GET /api/v1/evidence-packets/{id}/download
|
||||
POST /api/v1/audit-reports
|
||||
GET /api/v1/audit-reports/{id}
|
||||
GET /api/v1/audit-reports/{id}/download
|
||||
GET /api/v1/version-stickers
|
||||
GET /api/v1/version-stickers/{id}
|
||||
```
|
||||
|
||||
### Plugin Infrastructure (PLUGIN)
|
||||
|
||||
```
|
||||
GET /api/v1/plugins
|
||||
GET /api/v1/plugins/{id}
|
||||
POST /api/v1/plugins/{id}/enable
|
||||
POST /api/v1/plugins/{id}/disable
|
||||
GET /api/v1/plugins/{id}/health
|
||||
POST /api/v1/plugin-instances
|
||||
GET /api/v1/plugin-instances
|
||||
PUT /api/v1/plugin-instances/{id}
|
||||
DELETE /api/v1/plugin-instances/{id}
|
||||
```
|
||||
|
||||
## WebSocket Endpoints
|
||||
|
||||
```
|
||||
WS /api/v1/workflow-runs/{id}/stream
|
||||
WS /api/v1/deployment-jobs/{id}/stream
|
||||
WS /api/v1/agents/{id}/task-stream
|
||||
WS /api/v1/dashboard/stream
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
| Tier | Requests/minute | Burst |
|
||||
|------|-----------------|-------|
|
||||
| Standard | 1000 | 100 |
|
||||
| Premium | 5000 | 500 |
|
||||
|
||||
Rate limit headers:
|
||||
- `X-RateLimit-Limit`: Request limit
|
||||
- `X-RateLimit-Remaining`: Remaining requests
|
||||
- `X-RateLimit-Reset`: Reset timestamp
|
||||
|
||||
## References
|
||||
|
||||
- [Environments API](environments.md)
|
||||
- [Releases API](releases.md)
|
||||
- [Promotions API](promotions.md)
|
||||
- [Workflows API](workflows.md)
|
||||
- [Agents API](agents.md)
|
||||
- [WebSocket API](websockets.md)
|
||||
Reference in New Issue
Block a user