Text of pkg.go.dev › forge.lthn.ai › core › go-api as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

api package - forge.lthn.ai/core/go-api - Go Packages

README ¶ go-api REST framework + OpenAPI SDK generation for the Lethean Go ecosystem. Overview go-api provides a Gin-based HTTP engine that subsystems plug into via the RouteGroup interface. Each ecosystem package (go-ml, go-rag, go-agentic, etc.) registers its own route group, and go-api handles the HTTP plumbing, middleware, response envelopes, WebSocket integration, and OpenAPI spec generation. Quick Start import api "forge.lthn.ai/core/go-api" engine, _ := api.New( api.WithAddr(":8080"), api.WithBearerAuth("my-token"), api.WithCORS("*"), api.WithRequestID(), api.WithSwagger("My API", "Description", "0.1.0"), ) engine.Register(myRoutes) engine.Serve(ctx) Implementing a RouteGroup type Routes struct{ service *mypackage.Service } func (r *Routes) Name() string { return "mypackage" } func (r *Routes) BasePath() string { return "/v1/mypackage" } func (r *Routes) RegisterRoutes(rg *gin.RouterGroup) { rg.GET("/items", r.ListItems) rg.POST("/items", r.CreateItem) } func (r *Routes) ListItems(c *gin.Context) { items, _ := r.service.List(c.Request.Context()) c.JSON(200, api.OK(items)) } Authentik Integration engine, _ := api.New( api.WithAuthentik(api.AuthentikConfig{ Issuer: "https://auth.lthn.io/application/o/core-api/", ClientID: "core-api", TrustedProxy: true, // Read X-authentik-* headers from Traefik }), ) In handlers, use GetUser() to access the authenticated user: func (r *Routes) ListItems(c *gin.Context) { user := api.GetUser(c) // nil if unauthenticated if user != nil { // user.Username, user.Email, user.Groups, user.UID } } For protected routes, use RequireAuth() or RequireGroup() : func (r *Routes) RegisterRoutes(rg *gin.RouterGroup) { rg.GET("/public", r.PublicEndpoint) rg.GET("/private", api.RequireAuth(), r.PrivateEndpoint) rg.GET("/admin", api.RequireGroup("admins"), r.AdminEndpoint) } Features Response envelope — api.OK() , api.Fail() , api.Paginated() for consistent JSON responses Middleware — Bearer auth, CORS, request ID generation, panic recovery Authentik — Forward auth headers + OIDC JWT validation, RequireAuth() and RequireGroup() guards WebSocket — WithWSHandler() mounts any http.Handler at /ws Swagger UI — WithSwagger() serves interactive API docs at /swagger/ Health check — Built-in GET /health endpoint Licence EUPL-1.2 Documentation ¶ Overview ¶ Package api provides a Gin-based REST framework with OpenAPI generation.

Subsystems implement RouteGroup to register their own endpoints. Index ¶ Constants func ExportSpec(w io.Writer, format string, builder *SpecBuilder, groups []RouteGroup) error func ExportSpecToFile(path, format string, builder *SpecBuilder, groups []RouteGroup) error func GetLocale(c *gin.Context) string func GetMessage(c *gin.Context, key string) (string, bool) func NewTracerProvider(exporter sdktrace.SpanExporter) *sdktrace.TracerProvider func RequireAuth() gin.HandlerFunc func RequireGroup(group string) gin.HandlerFunc func SupportedLanguages() []string func SupportedLanguagesIter() iter.Seq[string] type AuthentikConfig type AuthentikUser func GetUser(c *gin.Context) *AuthentikUser func (u *AuthentikUser) HasGroup(group string) bool type DescribableGroup type Engine func New(opts ...Option) (*Engine, error) func (e *Engine) Addr() string func (e *Engine) Channels() []string func (e *Engine) ChannelsIter() iter.Seq[string] func (e *Engine) Groups() []RouteGroup func (e *Engine) GroupsIter() iter.Seq[RouteGroup] func (e *Engine) Handler() http.Handler func (e *Engine) Register(group RouteGroup) func (e *Engine) Serve(ctx context.Context) error type Error type GraphQLOption func WithGraphQLPath(path string) GraphQLOption func WithPlayground() GraphQLOption type I18nConfig type Meta type Option func WithAddr(addr string) Option func WithAuthentik(cfg AuthentikConfig) Option func WithAuthz(enforcer *casbin.Enforcer) Option func WithBearerAuth(token string) Option func WithBrotli(level ...int) Option func WithCORS(allowOrigins ...string) Option func WithCache(ttl time.Duration) Option func WithExpvar() Option func WithGraphQL(schema graphql.ExecutableSchema, opts ...GraphQLOption) Option func WithGzip(level ...int) Option func WithHTTPSign(secrets httpsign.Secrets, opts ...httpsign.Option) Option func WithI18n(cfg ...I18nConfig) Option func WithLocation() Option func WithMiddleware(mw ...gin.HandlerFunc) Option func WithPprof() Option func WithRequestID() Option func WithSSE(broker *SSEBroker) Option func WithSecure() Option func WithSessions(name string, secret []byte) Option func WithSlog(logger *slog.Logger) Option func WithStatic(urlPrefix, root string) Option func WithSwagger(title, description, version string) Option func WithTimeout(d time.Duration) Option func WithTracing(serviceName string, opts ...otelgin.Option) Option func WithWSHandler(h http.Handler) Option type Response func Fail(code, message string) Response[any] func FailWithDetails(code, message string, details any) Response[any] func OK[T any](data T) Response[T] func Paginated[T any](data T, page, perPage, total int) Response[T] type RouteDescription type RouteGroup type SDKGenerator func (g *SDKGenerator) Available() bool func (g *SDKGenerator) Generate(ctx context.Context, language string) error type SSEBroker func NewSSEBroker() *SSEBroker func (b *SSEBroker) ClientCount() int func (b *SSEBroker) Drain() func (b *SSEBroker) Handler() gin.HandlerFunc func (b *SSEBroker) Publish(channel, event string, data any) type SpecBuilder func (sb *SpecBuilder) Build(groups []RouteGroup) ([]byte, error) type StreamGroup type ToolBridge func NewToolBridge(basePath string) *ToolBridge func (b *ToolBridge) Add(desc ToolDescriptor, handler gin.HandlerFunc) func (b *ToolBridge) BasePath() string func (b *ToolBridge) Describe() []RouteDescription func (b *ToolBridge) DescribeIter() iter.Seq[RouteDescription] func (b *ToolBridge) Name() string func (b *ToolBridge) RegisterRoutes(rg *gin.RouterGroup) func (b *ToolBridge) Tools() []ToolDescriptor func (b *ToolBridge) ToolsIter() iter.Seq[ToolDescriptor] type ToolDescriptor Constants ¶ View Source const ( // BrotliBestSpeed is the lowest (fastest) Brotli compression level.

BrotliBestSpeed = brotli . BestSpeed // BrotliBestCompression is the highest (smallest output) Brotli level. BrotliBestCompression = brotli . BestCompression // BrotliDefaultCompression is the default Brotli compression level. BrotliDefaultCompression = brotli . DefaultCompression ) Variables ¶ This section is empty. Functions ¶ func ExportSpec ¶ func ExportSpec(w io . Writer , format string , builder * SpecBuilder , groups [] RouteGroup ) error ExportSpec generates the OpenAPI spec and writes it to w.

Format must be "json" or "yaml". func ExportSpecToFile ¶ func ExportSpecToFile(path, format string , builder * SpecBuilder , groups [] RouteGroup ) error ExportSpecToFile writes the spec to the given path. The parent directory is created if it does not exist. func GetLocale ¶ func GetLocale(c * gin . Context ) string GetLocale returns the detected locale for the current request. Returns "en" if the i18n middleware was not applied. func GetMessage ¶ func GetMessage(c * gin .

Context , key string ) ( string , bool ) GetMessage looks up a localised message by key for the current request. Returns the message string and true if found, or empty string and false if the key does not exist or the i18n middleware was not applied. func NewTracerProvider ¶ func NewTracerProvider(exporter sdktrace . SpanExporter ) * sdktrace . TracerProvider NewTracerProvider creates a TracerProvider configured with the given SpanExporter and returns it.

The caller is responsible for calling Shutdown on the returned provider when the application exits. This is a convenience helper for tests and simple deployments. Production setups should build their own TracerProvider with batching, resource attributes, and appropriate exporters. func RequireAuth ¶ func RequireAuth() gin . HandlerFunc RequireAuth is Gin middleware that rejects unauthenticated requests.

The rest of this page is on the live site.