Comprehensive guides and references for the OpenFrame platform
The Api Service Core Rest Controllers module exposes the primary internal REST endpoints for the OpenFrame API service. It acts as the HTTP boundary layer between external clients (Frontend, Gateway, Client Agents, and Internal Services) and the underlying domain services, repositories, and security infrastructure.
This module is responsible for:
It is part of the broader openframe-api-service-core library and runs inside the API application entry point.
Within the overall platform, the Api Service Core Rest Controllers module sits between:
flowchart TD
Client["Frontend / Gateway / Client Agents"] -->|"HTTP REST"| Controllers["Api Service Core Rest Controllers"]
Controllers -->|"Delegates"| AppServices["Application Services"]
AppServices -->|"Uses"| DomainServices["Domain Services"]
DomainServices -->|"Persists / Queries"| DataLayer["Mongo / Pinot / Kafka"]
Controllers -->|"Reads Principal"| Security["Security & Auth Context"]
flowchart TD
A["HTTP Request"] --> B["@RestController"]
B --> C["DTO Validation"]
C --> D["Application Service"]
D --> E["Domain / Repository"]
E --> F["Database / External System"]
F --> E
E --> D
D --> G["Response DTO"]
G --> H["HTTP Response"]
The controllers are intentionally thin: they orchestrate request handling and defer business logic to services.
The module contains the following controllers:
Each controller focuses on a well-defined domain boundary.
Several controllers rely on @AuthenticationPrincipal AuthPrincipal to retrieve:
Example flow:
flowchart TD
Request["Authenticated HTTP Request"] --> Filter["Security Filter Chain"]
Filter --> Principal["AuthPrincipal"]
Principal --> Controller["Controller Method"]
Controller --> Service["User / ApiKey Service"]
Controllers such as:
rely on the principal for user-scoped operations and tenant isolation.
Base Path: /agent/registration-secret
Manages secrets used for agent registration. These secrets are typically consumed by client-side components during onboarding.
GET /agent/registration-secret/active – Retrieve active secretGET /agent/registration-secret – List all secretsPOST /agent/registration-secret/generate – Generate a new secretAgentRegistrationSecretServiceBase Path: /api-keys
Manages user-scoped API keys for programmatic access.
GET /api-keys – List API keys for current userPOST /api-keys – Create API keyGET /api-keys/{keyId} – Retrieve specific keyPUT /api-keys/{keyId} – Update key metadataDELETE /api-keys/{keyId} – Delete keyPOST /api-keys/{keyId}/regenerate – Regenerate secretflowchart TD
User["Authenticated User"] --> Controller["ApiKeyController"]
Controller --> Service["ApiKeyService"]
Service --> Repo["API Key Repository"]
Controller -->|"principal.getId()"| Scope["User-Scoped Access"]
All operations are scoped by the authenticated user ID.
Base Path: /devices
Provides internal APIs for device state updates.
PATCH /devices/{machineId} – Update device statusThis endpoint is typically invoked by internal systems or agents to update operational state.
Base Path: /force
Triggers forced actions across clients and tool agents.
/all variants)flowchart TD
Admin["Admin Request"] --> Controller["ForceAgentController"]
Controller --> InstallService["ForceToolInstallationService"]
Controller --> UpdateService["ForceToolAgentUpdateService"]
Controller --> ClientService["ForceClientUpdateService"]
This controller orchestrates operational commands but does not directly manipulate infrastructure.
Endpoint: GET /health
Provides a lightweight health check endpoint returning 200 OK with body OK.
Used by:
Base Path: /invitations
Manages user invitations within a tenant.
POST /invitations – Create invitationGET /invitations – Paginated listDELETE /invitations/{id} – RevokePOST /invitations/{id}/resend – Renew invitationDelegates to InvitationService for lifecycle management.
Endpoint: GET /me
Returns current authenticated user context.
{
"authenticated": true,
"user": {
"id": "...",
"email": "...",
"displayName": "...",
"roles": [...],
"tenantId": "..."
}
}
If no principal is present, returns 401 Unauthorized.
Base Path: /openframe-client/configuration
Exposes runtime configuration required by OpenFrame clients.
GET /openframe-client/configurationDelegates to OpenFrameClientConfigurationQueryService.
Base Path: /organizations
Handles organization mutations (create, update, delete).
Read-only organization queries are handled elsewhere (e.g., external API layer).
POST /organizationsPUT /organizations/{id}DELETE /organizations/{id}IllegalArgumentException → 404 Not FoundOrganizationHasMachinesException → 409 Conflictflowchart TD
Request["Delete Organization"] --> Controller["OrganizationController"]
Controller --> Service["OrganizationCommandService"]
Service -->|"Has Machines?"| Check["Business Rule"]
Check -->|"Yes"| Conflict["409 Conflict"]
Check -->|"No"| Delete["Delete Organization"]
Base Path: /release-version
Exposes the current release version metadata.
GET /release-versionReturns 404 if no release version is present.
Base Path: /sso
Manages Single Sign-On provider configuration.
flowchart TD
Admin["Admin Request"] --> Controller["SSOConfigController"]
Controller --> Service["SSOConfigService"]
Service --> Store["Tenant SSO Configuration"]
Supports multi-tenant SSO configuration.
Base Path: /users
Manages user accounts within a tenant.
GET /users – Paginated listGET /users/{id} – Retrieve userPUT /users/{id} – Update userDELETE /users/{id} – Soft deleteDeletion uses both:
@Valid for request DTO validation201 Created for resource creation204 No Content for successful deletions404 Not Found for missing resources409 Conflict for domain rule violationsThe Api Service Core Rest Controllers module provides the internal REST interface for the API service. It:
By keeping controllers thin and service-driven, the module ensures:
This module forms the primary HTTP backbone of the OpenFrame API service.