API Reference
Complete endpoint reference for the Platform Registry. All endpoints require JWT authentication and run on port 8084. The service uses two base paths: /api/v1/registry for component and version management, and /api/v1/services for service discovery.
Components
| Method | Path | Description |
|---|---|---|
GET | /api/v1/registry/components | List all active components |
GET | /api/v1/registry/components/:id | Get component by ID |
GET | /api/v1/registry/components/by-name/:name | Get component by name |
GET | /api/v1/registry/components/categories | List active component categories |
GET | /api/v1/registry/components/category/:category | List components by category |
POST | /api/v1/registry/components | Register a new component |
Versions
| Method | Path | Description |
|---|---|---|
GET | /api/v1/registry/components/:componentId/versions | List all versions |
GET | /api/v1/registry/components/:componentId/versions/stable | List stable versions |
GET | /api/v1/registry/components/:componentId/versions/recommended | Get recommended version |
GET | /api/v1/registry/components/:componentId/versions/latest | Get latest version |
POST | /api/v1/registry/components/:componentId/versions | Register a new version |
PUT | /api/v1/registry/versions/:versionId/status | Update version status |
POST | /api/v1/registry/versions/:versionId/deprecate | Deprecate a version |
POST | /api/v1/registry/components/:componentId/versions/:versionId/set-recommended | Set recommended version |
GET | /api/v1/registry/versions/:versionId1/compare/:versionId2 | Compare two versions |
POST | /api/v1/registry/versions/:versionId/check-compatibility | Check version compatibility |
Upgrade Paths
| Method | Path | Description |
|---|---|---|
POST | /api/v1/registry/upgrade-paths | Register an upgrade path |
GET | /api/v1/registry/upgrade-paths/calculate | Calculate all upgrade paths |
GET | /api/v1/registry/upgrade-paths/optimal | Get optimal upgrade path |
GET | /api/v1/registry/versions/:versionId/upgrade-to-latest | Path to latest version |
GET | /api/v1/registry/versions/:versionId/upgrade-to-recommended | Path to recommended version |
GET | /api/v1/registry/versions/:versionId/upgrade-targets | List available upgrade targets |
POST | /api/v1/registry/upgrade-paths/validate | Validate an upgrade |
GET | /api/v1/registry/components/:componentId/upgrade-paths/zero-downtime | Zero-downtime paths |
Upgrade Execution
| Method | Path | Description |
|---|---|---|
POST | /api/v1/registry/tenants/:tenantId/upgrades | Initiate an upgrade |
POST | /api/v1/registry/upgrades/:executionId/start | Start the upgrade |
GET | /api/v1/registry/upgrades/:executionId | Get execution status |
GET | /api/v1/registry/tenants/:tenantId/upgrades | List tenant executions |
GET | /api/v1/registry/tenants/:tenantId/components/:componentId/upgrades/active | Get active execution |
POST | /api/v1/registry/upgrades/:executionId/promote-canary | Promote canary to full rollout |
POST | /api/v1/registry/upgrades/:executionId/pause | Pause an upgrade |
POST | /api/v1/registry/upgrades/:executionId/resume | Resume a paused upgrade |
POST | /api/v1/registry/upgrades/:executionId/cancel | Cancel an upgrade |
POST | /api/v1/registry/upgrades/:executionId/rollback | Initiate rollback |
GET | /api/v1/registry/components/:componentId/upgrade-statistics | Upgrade statistics |
Service Discovery
| Method | Path | Description |
|---|---|---|
POST | /api/v1/services/register | Register a service instance |
DELETE | /api/v1/services/:serviceName/instances/:instanceId | Deregister an instance |
GET | /api/v1/services | List all registered services |
GET | /api/v1/services/:serviceName | Get all instances of a service |
GET | /api/v1/services/:serviceName/healthy | Get healthy instances |
GET | /api/v1/services/:serviceName/instance | Get single instance (load balanced) |
GET | /api/v1/services/status | Service status summary |
Health
| Method | Path | Description |
|---|---|---|
GET | /api/v1/services/:serviceName/health | Aggregated service health |
GET | /api/v1/services/health | Platform-wide health |
POST | /api/v1/services/:serviceName/instances/:instanceId/health-check | Trigger health check |
Dependencies
| Method | Path | Description |
|---|---|---|
POST | /api/v1/services/:serviceName/dependencies | Add a service dependency |
GET | /api/v1/services/:serviceName/dependencies | Get service dependencies |
GET | /api/v1/services/:serviceName/dependents | Get dependent services |
GET | /api/v1/services/:serviceName/dependencies/health | Check dependency health |
GET | /api/v1/services/dependencies/graph | Full dependency graph |
Common Query Parameters
Upgrade Path Calculation
| Parameter | Type | Description |
|---|---|---|
fromVersionId | UUID | Source version identifier |
toVersionId | UUID | Target version identifier |
Version Status Update
| Parameter | Type | Description |
|---|---|---|
status | VersionStatus | New status value (ALPHA, BETA, RC, STABLE, DEPRECATED, END_OF_LIFE) |
Version Deprecation
| Parameter | Type | Description |
|---|---|---|
endOfSupportDate | LocalDate | Date when support ends (format: YYYY-MM-DD) |
Rollback
| Parameter | Type | Required | Description |
|---|---|---|---|
reason | String | No | Reason for the rollback (defaults to "Manual rollback requested") |
Error Responses
| Status | Condition |
|---|---|
400 | Invalid request parameters or version validation failure |
404 | Component, version, execution, or service instance not found |
409 | Component name or version already exists, or duplicate dependency |
422 | Upgrade validation failed (blockers present) |
500 | Internal server error |