Skip to content

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

TypeDescription
OkapiMain application struct — all fields unexported; configure via options/methods
Context (aliases: C, Ctx)Per-request context with store, binding, response helpers
RouteRegistered route with metadata
RouteDefinitionDeclarative route definition struct
GroupRoute group with shared prefix, middleware, security, tags
GroupTagNamed OpenAPI tag with description + external docs
HandlerFuncfunc(*Context) error
Middleware / MiddlewareFuncType aliases of HandlerFunc — call c.Next() inside
RouteOptionfunc(*Route) — composable route configuration
OptionFuncfunc(*Okapi) — composable app configuration
Mmap[string]any shorthand
ResponseWriterExtended http.ResponseWriter (status, byte count, hijack, flush, push, close)
Renderer / RendererFuncTemplate rendering interface + function adapter
Template / TemplateConfigBuilt-in html/template loader
ErrorHandlerfunc(*Context, int, string, error) error
ErrorHandlerConfig / ProblemDetailRFC 7807 configuration and payload
ErrorResponse / ValidationError / ValidationErrorResponseDefault error payloads
CorsCORS configuration struct
BasicAuth / JWTAuth / BodyLimitBuilt-in middleware structs
Jwks / JwkJWKS key material
OpenAPIOpenAPI document configuration
DocUIUI selector (SwaggerUI, RedocUI, ScalarUI)
DocBuilderFluent route documentation builder (okapi.Doc())
SchemaInfoReusable component schema registration
Message / StreamOptions / SerializerSSE primitives
WebConfigSPA / web app serving configuration
TestServer / TestingTTest 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.

OptionDescription
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

TopicSkill
Methods, paths, groups, fallbacksrouting/
Declarative route structsroute_definition/
Binding sources and methodsrequest_binding/
Struct-tag validation and formatsvalidation/
Writing responsesresponse/
Aborts, error handlers, RFC 7807error_handling/
Specs, UIs, doc options, webhooksopenapi/
JWT, Basic auth, CORSauthentication/
Built-in and custom middlewaremiddleware/
Runtime enable/disabledynamic_routes/
Server-Sent Eventssse_stream/
WebSockets (okapiws)websocket/
Outbound HTTP clienthttp_client/
Test server and assertionstesting/
Flags, subcommands, lifecyclecli/
Context utilitiescontext/
Templates and rendererstemplating/
SPA / static servingweb_spa/
TLS, mTLS, autocerttls_https/
net/http interopstd_compat/
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall