Documentation
¶
Overview ¶
Package v2 is the oCMS REST API v2, served at /api/v2.
Every operation is registered via huma.Register with typed input and output structs. The OpenAPI 3.1 document served at /api/v2/openapi.json is derived from those types — by construction the spec and the handlers cannot drift.
This package MUST NOT import internal/handler/api (the v1 surface). v2 is a fresh rewrite; the old package will be deleted as each domain migrates.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( APIKeyAuthSecurity = []map[string][]string{{"ApiKeyAuth": {}}} PagesWriteSecurity = []map[string][]string{{"ApiKeyAuth": {"pages:write"}}} MediaWriteSecurity = []map[string][]string{{"ApiKeyAuth": {"media:write"}}} TaxonomyWriteSecurity = []map[string][]string{{"ApiKeyAuth": {"taxonomy:write"}}} )
APIKeyAuthSecurity is the base Security block for any operation that just needs a valid API key regardless of permission (e.g., /auth meta endpoint). Write operations should use the permission-scoped variants below so the runtime middleware can short-circuit a wrong-permission call BEFORE huma parses the request body — a read-only key sending `POST /media` is rejected with 403 without any multipart work. The scope string must match one of `model.Permission*` constants so services and the OpenAPI spec stay aligned.
Functions ¶
Types ¶
type Actor ¶
Actor describes the principal making a v2 request. APIKey is nil for unauthenticated callers; Permissions is parsed once so services can make authorization decisions without re-querying the key.
func ActorFromContext ¶
ActorFromContext extracts the authenticated principal (if any) from a huma handler's request context. Returns a zero Actor for public callers.
func (Actor) HasPermission ¶
HasPermission reports whether the actor's API key grants a permission.
type AuthBody ¶
type AuthBody struct {
KeyPrefix string `json:"key_prefix" doc:"Public prefix of the API key used for display and correlation."`
Name string `json:"name" doc:"Human-readable name assigned to the key."`
Permissions []string `json:"permissions" doc:"Permission scopes granted to the key."`
}
AuthBody describes the authenticated API key for GET /api/v2/auth.
type Deps ¶
type Deps struct {
DB *sql.DB
Queries *store.Queries
Cache *cache.Manager
Events *service.EventService
}
Deps bundles dependencies that domain services may pick from.
type DocsServer ¶
type DocsServer struct {
// contains filtered or unexported fields
}
DocsServer renders /api/v2/docs (Swagger UI) and serves /api/v2/openapi.json and /api/v2/openapi.yaml. The spec is pulled live from the huma API so it always matches the currently-registered operations.
func NewDocsServer ¶
func NewDocsServer(templatesFS fs.FS, h *Handler) (*DocsServer, error)
NewDocsServer parses the embedded Swagger UI template and binds it to the v2 huma handler.
func (*DocsServer) ServeDocs ¶
func (s *DocsServer) ServeDocs(w http.ResponseWriter, r *http.Request)
ServeDocs renders the Swagger UI page.
func (*DocsServer) ServeOpenAPIJSON ¶
func (s *DocsServer) ServeOpenAPIJSON(w http.ResponseWriter, _ *http.Request)
ServeOpenAPIJSON emits the live huma-built OpenAPI 3.1 document as JSON.
func (*DocsServer) ServeOpenAPIYAML ¶
func (s *DocsServer) ServeOpenAPIYAML(w http.ResponseWriter, _ *http.Request)
ServeOpenAPIYAML emits the same document as YAML, round-tripped through JSON so upstream types don't need YAML struct tags.
type Error ¶
type Error struct {
Kind ErrorKind
Fields map[string]string // per-field validation errors, surfaced as error.details
Msg string
Wrap error
}
Error is the domain error type returned from services. Callers (v2 huma operation handlers) translate it via ToHuma.
func NewValidationError ¶
NewValidationError constructs a validation error carrying per-field messages.
type ErrorBody ¶
type ErrorBody struct {
Error ErrorDetail `json:"error"`
}
ErrorBody is the JSON envelope emitted for every error response.
{"error": {"code": "...", "message": "...", "details": {"field": "msg"}}}
type ErrorDetail ¶
type ErrorDetail struct {
Code string `json:"code"`
Message string `json:"message"`
Details map[string]string `json:"details,omitempty"`
}
ErrorDetail is the inner error payload.
type ErrorKind ¶
type ErrorKind int
ErrorKind classifies domain errors so services can express semantic meaning without depending on HTTP. Huma adapters translate ErrorKind into status codes; the on-wire "code" string stays stable across transports.
type Handler ¶
Handler holds the live huma.API plus shared deps.
type StatusBody ¶
type StatusBody struct {
Status string `json:"status" example:"ok" doc:"'ok' when the API is reachable."`
Version string `json:"version" example:"v2" doc:"API major version."`
}
StatusBody is the API availability payload returned by GET /api/v2/status.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package media is the /api/v2/media domain.
|
Package media is the /api/v2/media domain. |
|
Package pages is the /api/v2/pages domain.
|
Package pages is the /api/v2/pages domain. |
|
Package taxonomy is the /api/v2/tags and /api/v2/categories domain.
|
Package taxonomy is the /api/v2/tags and /api/v2/categories domain. |