stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4a98dfef353e6065bb8daaa43c05943205fd49
git.stella-ops.org/docs/modules/release-orchestrator/api/overview.md

7.5 KiB
Raw Blame History

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:

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

interface ApiResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    requestId: string;
    timestamp: string;
  };
}

Error Response

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

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