Overview

Okapi Overview

> A modern, minimalist HTTP framework for Go built for simplicity, performance, and developer experience. > Module: github.com/jkaninda/okapi — requires Go 1.25+. Implements http.Handler, fully net/http compatible. > Routing is provided by github.com/jkaninda/njia (Okapi's own router; it replaced the archived gorilla/mux in v0.10.0).

go get github.com/jkaninda/okapi

Project Structure

okapi.go          - Core framework (Okapi struct, options, server lifecycle, route registration)
router_register.go- Router registration helpers
context.go        - Request/response context (data store, binding, responses, SSE, errors)
route.go          - Route and RouteDefinition types, route options
group.go          - Route groups with prefix, middleware, security, tags
binder.go         - Request binding (JSON, XML, YAML, Protobuf, form, multipart, query, header, path, cookie)
validator.go      - Struct tag validation (min/max, length, pattern, enum, format, const, conditional required)
openapi.go        - OpenAPI 3.0/3.1 spec generation, doc options, DocBuilder, webhooks
doc.go            - Swagger UI / ReDoc / Scalar HTML templates and endpoints
middlewares.go    - Built-in middleware (Logger, BasicAuth, JWTAuth, BodyLimit, RequestID)
jwt.go            - JWT token generation, validation, key resolution
jwks.go           - JWKS loading (remote URL, file, base64)
jwt_claims_expression.go - DSL for JWT claim validation (Equals, Contains, OneOf, Prefix; &&, ||, !)
cors.go           - CORS handler configuration (origins, wildcards, credentials)
sse.go            - Server-Sent Events (Message, StreamOptions, serializers)
template.go       - HTML template loading (files, directory, embedded FS, config)
renderer.go       - Renderer interface and RendererFunc adapter
errors.go         - Error types (ErrorResponse, ValidationError, ProblemDetail RFC 7807), Abort/Error helpers
static.go         - Static files and Web/WebFS SPA serving with index fallback
tests.go          - TestServer and NewTestContext for tests
util.go           - Utilities (LoadTLSConfig, ValidateAddr, status-class helpers)
helper.go         - Internal helpers
constants.go      - Default values, tag names, format types
var.go            - Package-level variables
client/           - Fluent HTTP client (retries, middleware, decoders, JSON/XML/YAML/multipart)
okapitest/        - Fluent HTTP test client (verbs + status/body/header/JSON-path assertions)
okapicli/         - CLI integration (flags, env config, subcommands, struct config, lifecycle hooks)
examples/         - Runnable examples (sample, group, middleware, tls, sse, template, web, cli, client, tests, std, ...)

Core Types

| Type | Description | |------|-------------| | Okapi | Main application struct — all fields unexported; configure via options/methods | | Context (aliases: C, Ctx) | Per-request context with store, binding, response helpers | | Route | Registered route with metadata | | RouteDefinition | Declarative route definition struct | | Group | Route group with shared prefix, middleware, security, tags | | GroupTag | Named OpenAPI tag with description + external docs | | HandlerFunc | func(*Context) error | | Middleware / MiddlewareFunc | Type aliases of HandlerFunc — call c.Next() inside | | RouteOption | func(*Route) — composable route configuration | | OptionFunc | func(*Okapi) — composable app configuration | | M | map[string]any shorthand | | ResponseWriter | Extended http.ResponseWriter (status, byte count, hijack, flush, push, close) | | Renderer / RendererFunc | Template rendering interface + function adapter | | Template / TemplateConfig | Built-in html/template loader | | ErrorHandler | func(*Context, int, string, error) error | | ErrorHandlerConfig / ProblemDetail | RFC 7807 configuration and payload | | ErrorResponse / ValidationError / ValidationErrorResponse | Default error payloads | | Cors | CORS configuration struct | | BasicAuth / JWTAuth / BodyLimit | Built-in middleware structs | | Jwks / Jwk | JWKS key material | | OpenAPI | OpenAPI document configuration | | DocUI | UI selector (SwaggerUI, RedocUI, ScalarUI) | | DocBuilder | Fluent route documentation builder (okapi.Doc()) | | SchemaInfo | Reusable component schema registration | | Message / StreamOptions / Serializer | SSE primitives | | WebConfig | SPA / web app serving configuration | | TestServer / TestingT | Test server helpers |

Constructors

• okapi.New(options ...OptionFunc) *Okapi — minimal instance (no docs, no access log)
• okapi.Default() *Okapi — logger middleware + access log + OpenAPI docs enabled
• okapi.NewGroup(basePath string, o *Okapi, middlewares ...Middleware) *Group
• okapi.NewContext(o *Okapi, w http.ResponseWriter, r *http.Request) *Context

App Configuration

Most options exist both as an OptionFunc (for New() / With()) and as a chainable method on *Okapi.

| Option | Description | |--------|-------------| | WithPort(port int) | Server port (default 8080) | | WithAddr(addr string) | Server address (default :8080) | | WithServer(*http.Server) | Supply a fully configured *http.Server (option only) | | WithTLS(*tls.Config) | Serve HTTPS on the main server | | WithTLSServer(addr string, *tls.Config) | Additional HTTPS listener alongside HTTP (option only) | | WithCors(cors Cors) (option) / WithCORS(cors Cors) (method) | CORS configuration | | WithLogger(*slog.Logger) | Structured logger | | WithContext(context.Context) | Application context | | WithDebug() | Debug mode + access logging | | WithAccessLogDisabled() (option) / DisableAccessLog() (method) | Disable access logging | | WithReadTimeout(s int) / WithWriteTimeout(s int) / WithIdleTimeout(s int) | Server timeouts (seconds) | | WithStrictSlash(strict bool) | Trailing-slash redirect behaviour | | WithMaxMultipartMemory(max int64) | Multipart memory limit (default 32 MB) | | WithOpenAPIDocs(cfg ...OpenAPI) | Enable/configure OpenAPI docs | | WithOpenAPIDisabled() | Disable OpenAPI docs | | WithDocUI(ui DocUI) | Pick SwaggerUI / RedocUI / ScalarUI for /docs | | WithRenderer(Renderer) | Set the template renderer | | WithDefaultRenderer(pattern string) (method) | Renderer from a file pattern | | WithRendererFromFS(fsys fs.FS, pattern string) (method) | Renderer from an embedded FS | | WithRendererFromDirectory(dir string, ext ...string) (method) | Renderer from a directory | | WithRendererConfig(TemplateConfig) (method) | Renderer from a config struct | | WithErrorHandler(ErrorHandler) | Custom error handler | | WithDefaultErrorHandler() | Reset to the default error handler | | WithProblemDetailErrorHandler(*ErrorHandlerConfig) | RFC 7807 errors | | WithSimpleProblemDetailErrorHandler() | RFC 7807 with defaults | | WithMuxRouter(*njia.Router) | Deprecated no-op — Okapi manages its own router |

o.With(options ...OptionFunc) *Okapi applies options to an existing instance.

Server Lifecycle

o.Start() error                                  // start on the configured addr (HTTPS if TLSConfig set)
o.StartOn(port int) error                        // start on a specific port
o.StartServer(server *http.Server) error         // start with a supplied server
o.Stop() error                                   // graceful shutdown of HTTP + HTTPS listeners
o.StopWithContext(ctx context.Context) error     // graceful shutdown with a deadline
o.Shutdown(server *http.Server, ctx ...context.Context) error // deprecated — use StopWithContext
o.WaitForServer(timeout time.Duration) string    // block until ready, return the address
o.StartForTest(t TestingT) string                // start for a test, return the base URL
o.ServeHTTP(w, r)                                // Okapi is an http.Handler
o.GetContext() *Context / o.SetContext(*Context)

Graceful shutdown with signals is handled for you by okapicli (cli.Run() / cli.RunServer(...)) — see the cli/ skill.

Route Registration

o.Get/Post/Put/Delete/Patch/Head/Options/Any(path, handler, ...opts) *Route
o.Handle(method, path, handler, ...opts)                    // generic registration
o.HandleStd(method, path, http.HandlerFunc, ...opts)        // std-lib handler
o.HandleHTTP(method, path, http.Handler, ...opts)           // http.Handler
o.Register(routes ...RouteDefinition)                       // declarative bulk registration
okapi.RegisterRoutes(o, []RouteDefinition)                  // package-level equivalent
o.Group(prefix, ...middleware) *Group                       // route group
o.Use(...Middleware)                                        // global middleware
o.UseMiddleware(func(http.Handler) http.Handler)            // std-lib middleware bridge
o.NoRoute(handler) / o.NoMethod(handler)                    // 404 / 405 fallbacks
o.Webhook(name, method, ...opts) *Route                     // OpenAPI 3.1 webhook (docs-only)
o.RegisterSchemas(map[string]*SchemaInfo) error             // reusable component schemas
o.Routes() []Route                                          // introspection snapshot

Static Files & Web Apps

o.Static(prefix, dir)                    // serve a directory (no listing)
o.StaticFile(path, filepath)             // serve a single file
o.StaticFS(prefix, http.FileSystem)      // serve from any http.FileSystem
o.Web(prefix, dir, ...WebConfig)         // SPA from disk, index fallback
o.WebFS(prefix, fs.FS, ...WebConfig)     // SPA from an fs.FS / embed.FS
o.SPA(...) / o.SPAFS(...)                // deprecated aliases of Web / WebFS

Package-Level Helpers

okapi.GenerateJwtToken(secret []byte, claims jwt.MapClaims, ttl time.Duration) (string, error)
okapi.LoadJWKSFromFile(pathOrBase64 string) (*Jwks, error)
okapi.LoadTLSConfig(certFile, keyFile, caFile string, clientAuth bool) (*tls.Config, error)
okapi.ValidateAddr(addr string) bool
okapi.IsError(code int) bool / IsClientError(code int) bool / IsServerError(code int) bool
okapi.DefaultErrorHandler(c, code, message, err) error
okapi.ProblemDetailErrorHandler(cfg *ErrorHandlerConfig) ErrorHandler

Minimal Application

package main

import "github.com/jkaninda/okapi"

func main() {
    o := okapi.Default() // logger + OpenAPI docs at /docs

    o.Get("/", func(c *okapi.Context) error {
        return c.OK(okapi.M{"message": "Hello from Okapi!"})
    })

    if err := o.Start(); err != nil {
        panic(err)
    }
}

Skill Map

| Topic | Skill | |-------|-------| | Methods, paths, groups, fallbacks | routing/ | | Declarative route structs | route_definition/ | | Binding sources and methods | request_binding/ | | Struct-tag validation and formats | validation/ | | Writing responses | response/ | | Aborts, error handlers, RFC 7807 | error_handling/ | | Specs, UIs, doc options, webhooks | openapi/ | | JWT, Basic auth, CORS | authentication/ | | Built-in and custom middleware | middleware/ | | Runtime enable/disable | dynamic_routes/ | | Server-Sent Events | sse_stream/ | | WebSockets (okapiws) | websocket/ | | Outbound HTTP client | http_client/ | | Test server and assertions | testing/ | | Flags, subcommands, lifecycle | cli/ | | Context utilities | context/ | | Templates and renderers | templating/ | | SPA / static serving | web_spa/ | | TLS, mTLS, autocert | tls_https/ | | net/http interop | std_compat/ |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jkaninda
• Source: jkaninda/okapi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.