Skip to content
SHC Docs

API design

SHC uses go-chi with Frappe-style API paths and Unix socket communication between CLI and server.

SHC follows Frappe-style API conventions with no version prefix in URLs:

POST /api/method/shc.{module}.{operation}

Examples:

  • POST /api/method/shc.stack.install - Install a stack
  • POST /api/method/shc.backup.create - Create a backup
  • POST /api/method/shc.vault.get - Get a vault secret
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 stacks
  • GET /api/resource/Stack/my-app - Get specific stack
  • POST /api/resource/Stack - Create a stack
  • DELETE /api/resource/Stack/my-app - Delete a stack
  1. No Version in URL - We use /api/method/... not /api/v1/method/...
  2. Pre-1.0 - Breaking API or error-code changes are allowed; document them in release notes.
  3. Additive changes - Prefer new fields and endpoints over ambiguous overloads of existing ones.
  4. Frappe Alignment - Consistent with Frappe framework patterns
// modules/{module}/router.go
package {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})
}
}

Use JSON-RPC style method names:

OperationPatternExample
Listshc.{module}.listshc.backup.list
Getshc.{module}.getshc.backup.get
Createshc.{module}.createshc.backup.create
Updateshc.{module}.updateshc.backup.update
Deleteshc.{module}.deleteshc.backup.delete
types.go
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})

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})
}
}

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})
}
}

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"`
}

Context is passed via headers:

HeaderPurpose
traceparentW3C Trace Context (00-{trace_id}-{span_id}-01)
X-SHC-TenantTenant name (populates ctx.tenant_name)
X-SHC-StackStack name (populates ctx.stack_name)
X-SHC-EnvironmentEnvironment name (populates ctx.environment)
X-SHC-ActorWho initiated the request (ctx.actor)
X-SHC-OperationOperation ID for SSE progress routing (defaults to trace_id)
AuthorizationBearer <token>, Keycloak access token (required on TCP listeners)
X-Forwarded-ForClient 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.

Long-running operations (backup, restore, recover) use Server-Sent Events for real-time progress:

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}
Event TypePurposeData Fields
stepProgress updatestep, progress, message
completeOperation succeededOperation-specific result data
errorOperation failederror_code, error_message
EndpointOperation
POST /api/method/shc.backup.create_asyncStart backup
POST /api/method/shc.backup.restore_asyncStart restore
POST /api/method/shc.backup.recover_asyncStart recovery
GET /api/method/shc.operation.stream/{operation_id}Stream progress
GET /api/method/shc.operation.state/{operation_id}Query current state

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 operation
resp, err := client.Post("/api/method/shc.backup.create_async", map[string]any{
"stack_name": "myapp",
})
operationID := resp.OperationID
// Stream progress via SSE
events, 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
}
}
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)
},
)
err := client.UploadFile(
"/api/method/shc.backup.import",
"/tmp/backup.bak",
func(sent, total int64) {
fmt.Printf("%d/%d\n", sent, total)
},
)