API design
Overview
Section titled “Overview”SHC uses go-chi with Frappe-style API paths and Unix socket communication between CLI and server.
URL Structure
Section titled “URL Structure”SHC follows Frappe-style API conventions with no version prefix in URLs:
Method API (RPC-style operations)
Section titled “Method API (RPC-style operations)”POST /api/method/shc.{module}.{operation}Examples:
POST /api/method/shc.stack.install- Install a stackPOST /api/method/shc.backup.create- Create a backupPOST /api/method/shc.vault.get- Get a vault secret
Resource API (CRUD operations)
Section titled “Resource API (CRUD operations)”GET /api/resource/{ResourceType}GET /api/resource/{ResourceType}/{id}POST /api/resource/{ResourceType}PUT /api/resource/{ResourceType}/{id}DELETE /api/resource/{ResourceType}/{id}Examples:
GET /api/resource/Stack- List all stacksGET /api/resource/Stack/my-app- Get specific stackPOST /api/resource/Stack- Create a stackDELETE /api/resource/Stack/my-app- Delete a stack
Key Principles
Section titled “Key Principles”- No Version in URL - We use
/api/method/...not/api/v1/method/... - Pre-1.0 - Breaking API or error-code changes are allowed; document them in release notes.
- Additive changes - Prefer new fields and endpoints over ambiguous overloads of existing ones.
- Frappe Alignment - Consistent with Frappe framework patterns
Route Structure
Section titled “Route Structure”// modules/{module}/router.gopackage {module}
import ( "github.com/go-chi/chi/v5"
"gitlab.com/bitspur/selfhosted-cloud/ce/core/api")
func buildRouter(deps registry.Deps) http.Handler { r := chi.NewRouter() r.Post("/api/method/shc.{module}.create", createHandler()) return r}
func createHandler() http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { var req CreateRequest if err := validation.DecodeAndValidate(r.Body, &req); err != nil { api.WriteError(w, err) return } // ... business logic via Service ... api.WriteJSON(w, api.MethodResponse[CreateResponse]{Message: out}) }}Method Naming
Section titled “Method Naming”Use JSON-RPC style method names:
| Operation | Pattern | Example |
|---|---|---|
| List | shc.{module}.list | shc.backup.list |
| Get | shc.{module}.get | shc.backup.get |
| Create | shc.{module}.create | shc.backup.create |
| Update | shc.{module}.update | shc.backup.update |
| Delete | shc.{module}.delete | shc.backup.delete |
Request/Response Types
Section titled “Request/Response Types”package backup
import "time"
type BackupRequest struct { StackName string `json:"stack_name" validate:"required,min=1,max=255"` Environment string `json:"environment,omitempty"` IncludeVault bool `json:"include_vault,omitempty"`}
type BackupResponse struct { ID string `json:"id"` StackName string `json:"stack_name"` CreatedAt time.Time `json:"created_at"` SizeBytes int64 `json:"size_bytes"`}
// Wire responses live inside the Frappe-style `{"message": <T>}`// envelope. core/api supplies the generic wrapper://// api.WriteJSON(w, api.MethodResponse[BackupResponse]{Message: out})Context Injection
Section titled “Context Injection”The chi router uses middleware to populate a *ctx.Ctx carrying
tenant / stack / environment / actor; handlers read it via
ctx.FromRequest(r).
func createHandler(svc *Service) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { c := ctx.FromRequest(r) var req BackupRequest if err := validation.DecodeAndValidate(r.Body, &req); err != nil { api.WriteError(w, err) return } out, err := svc.Create(r.Context(), c, req) if err != nil { api.WriteError(w, err) return } api.WriteJSON(w, api.MethodResponse[BackupResponse]{Message: out}) }}Error Handling
Section titled “Error Handling”Errors flow through api.WriteError(w, err) which type-asserts to
*coded.CodedError and emits the canonical {error_code, message, http_status} envelope.
func getStackHandler(svc *Service) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { var req GetRequest if err := validation.DecodeAndValidate(r.Body, &req); err != nil { api.WriteError(w, err) return } stack, err := svc.Get(r.Context(), req.Name) if err != nil { api.WriteError(w, err) return } if stack == nil { api.WriteError(w, X404908STKNFD(req.Name)) return } api.WriteJSON(w, api.MethodResponse[*StackResponse]{Message: stack}) }}Pagination
Section titled “Pagination”Use cursor-based pagination for list endpoints:
type ListRequest struct { Limit int `json:"limit,omitempty" validate:"omitempty,gte=1,lte=100"` Cursor string `json:"cursor,omitempty"`}
type ListResponse struct { Items []Item `json:"items"` NextCursor string `json:"next_cursor,omitempty"` Total int `json:"total"`}Headers
Section titled “Headers”Context is passed via headers:
| Header | Purpose |
|---|---|
traceparent | W3C Trace Context (00-{trace_id}-{span_id}-01) |
X-SHC-Tenant | Tenant name (populates ctx.tenant_name) |
X-SHC-Stack | Stack name (populates ctx.stack_name) |
X-SHC-Environment | Environment name (populates ctx.environment) |
X-SHC-Actor | Who initiated the request (ctx.actor) |
X-SHC-Operation | Operation ID for SSE progress routing (defaults to trace_id) |
Authorization | Bearer <token>, Keycloak access token (required on TCP listeners) |
X-Forwarded-For | Client IP (from proxies) |
The public API serves both a TCP listener and a Unix domain socket
listener. Requests arriving over the UDS listener are marked by the
UDS middleware in modules/auth/ and bypass Keycloak as a
local superadmin (filesystem permissions on the socket are the
trust boundary). Every other transport (TCP, WebSocket, internal
API) must authenticate via Keycloak; see
modules/auth/service.go::ValidateBearer.
SSE Progress Streaming
Section titled “SSE Progress Streaming”Long-running operations (backup, restore, recover) use Server-Sent Events for real-time progress:
Two-Phase Pattern
Section titled “Two-Phase Pattern”sequenceDiagram participant CLI participant Server as Server (Unix Socket)
CLI->>Server: POST /api/method/shc.backup.create_async Server-->>CLI: operation_id (immediately) CLI->>Server: GET /api/method/shc.operation.stream/{operation_id} (SSE stream) Server-->>CLI: event: step {"step": "validating", "progress": 10} Server-->>CLI: event: step {"step": "archiving", "progress": 60} Server-->>CLI: event: complete {"backup_id": "abc123", "success": true}SSE Event Types
Section titled “SSE Event Types”| Event Type | Purpose | Data Fields |
|---|---|---|
step | Progress update | step, progress, message |
complete | Operation succeeded | Operation-specific result data |
error | Operation failed | error_code, error_message |
Async Endpoints
Section titled “Async Endpoints”| Endpoint | Operation |
|---|---|
POST /api/method/shc.backup.create_async | Start backup |
POST /api/method/shc.backup.restore_async | Start restore |
POST /api/method/shc.backup.recover_async | Start recovery |
GET /api/method/shc.operation.stream/{operation_id} | Stream progress |
GET /api/method/shc.operation.state/{operation_id} | Query current state |
Client Usage
Section titled “Client Usage”The CLI’s daemon_client.go per-module helpers wrap the SSE consume
path. ReadSSEStream (modules/app/commands/operation_sse.go, ce
module) is the streaming decoder; it feeds each parsed frame to an
onFrame callback and returns on the terminal event.
// Start async operationresp, err := client.Post("/api/method/shc.backup.create_async", map[string]any{ "stack_name": "myapp",})operationID := resp.OperationID
// Stream progress via SSEevents, err := client.StreamSSE(fmt.Sprintf( "/api/method/shc.operation.stream/%s", operationID))for event := range events { switch event.Type { case "step": fmt.Printf("[%d%%] %s\n", event.Data["progress"], event.Data["message"]) case "complete": fmt.Printf("Done: %v\n", event.Data) return case "error": fmt.Printf("Error: %s\n", event.Data["error_message"]) return }}File Transfer
Section titled “File Transfer”Export (Download)
Section titled “Export (Download)”err := client.DownloadFile( fmt.Sprintf("/api/method/shc.backup.export/%s", backupID), "/tmp/backup.bak", func(sent, total int64) { fmt.Printf("%d/%d\n", sent, total) },)Import (Upload)
Section titled “Import (Upload)”err := client.UploadFile( "/api/method/shc.backup.import", "/tmp/backup.bak", func(sent, total int64) { fmt.Printf("%d/%d\n", sent, total) },)