Home › API Reference

API Reference

Complete API documentation for all Lokstra packages

This section provides comprehensive API documentation for every exported type, function, and method in the Lokstra framework.

📚 Quick Navigation

Core Framework

Start here for building Lokstra applications:

  • lokstra - Main package (NewRouter, NewApp, NewServer)
  • Router - HTTP routing and handler registration
  • App - Application listener and lifecycle
  • Server - Server management and graceful shutdown
  • Request Context - Request handling and context
  • Response - Response helpers and formatting
  • Service - Service utilities (LazyLoad, dependency injection)

Registry & Configuration

Service registration, middleware, and configuration:

HTTP Client

Remote service communication:

Built-in Middleware

Ready-to-use middleware:

Note: JWT Auth and Access Control middleware have been moved to github.com/primadi/lokstra-auth

Built-in Services

Standard services and service APIs:

Note: Authentication services have been moved to github.com/primadi/lokstra-auth

Helper Packages

Utility functions and helpers:

Advanced Topics

Internal mechanisms and advanced patterns:

  • Proxy - Remote service proxy (core/proxy)
  • Route - Route definition internals (core/route)
  • Auto-Router - Auto-router generation
  • Handler Utils - Built-in handlers (SPA, static, reverse proxy)

📦 Package Index

Import Paths

// Core framework
import "github.com/primadi/lokstra"
import "github.com/primadi/lokstra/core/router"
import "github.com/primadi/lokstra/core/app"
import "github.com/primadi/lokstra/core/server"
import "github.com/primadi/lokstra/core/request"
import "github.com/primadi/lokstra/core/response"
import "github.com/primadi/lokstra/core/service"

// Registry & config
import "github.com/primadi/lokstra/lokstra_registry"
import "github.com/primadi/lokstra/core/config"
import "github.com/primadi/lokstra/core/deploy"
import "github.com/primadi/lokstra/core/deploy/schema"

// Client
import "github.com/primadi/lokstra/api_client"

// Middleware (auto-registered when imported)
import _ "github.com/primadi/lokstra/middleware/cors"
import _ "github.com/primadi/lokstra/middleware/request_logger"
// ... see 05-middleware for complete list
// Auth middleware moved to: github.com/primadi/lokstra-auth

// Services (auto-registered when imported)
import _ "github.com/primadi/lokstra/services/dbpool_pg"
import _ "github.com/primadi/lokstra/services/redis"
// ... see 06-services for complete list
// Auth services moved to: github.com/primadi/lokstra-auth

// Service APIs
import "github.com/primadi/lokstra/serviceapi/db_pool"
import "github.com/primadi/lokstra/serviceapi/kvstore"
// Auth service APIs moved to: github.com/primadi/lokstra-auth
import "github.com/primadi/lokstra/serviceapi/auth"

// Helpers
import "github.com/primadi/lokstra/common/cast"
import "github.com/primadi/lokstra/common/json"
import "github.com/primadi/lokstra/common/validator"
import "github.com/primadi/lokstra/common/utils"
import "github.com/primadi/lokstra/common/customtype"
import "github.com/primadi/lokstra/common/response_writer"

// Advanced
import "github.com/primadi/lokstra/core/proxy"
import "github.com/primadi/lokstra/core/route"
import "github.com/primadi/lokstra/lokstra_handler"

🎯 Common Use Cases

Building a Basic API

import "github.com/primadi/lokstra"

router := lokstra.NewRouter("api")
router.GET("/users", getUsersHandler)
router.POST("/users", createUserHandler)

app := lokstra.NewApp("api", ":8080", router)
server := lokstra.NewServer("my-server", app)
if err := server.Run(30 * time.Second); err != nil {
  fmt.Println("Error starting server:", err)
}

📖 See: lokstra, Router

Using Services with Dependency Injection

import "github.com/primadi/lokstra/lokstra_registry"
import "github.com/primadi/lokstra/core/service"

// Register service
lokstra_registry.RegisterServiceType("user-service",
    userServiceFactory, nil,
    deploy.WithResource("user", "users"),
)

// Use in another service
type OrderService struct {
    userService *service.Cached[*UserService]
}

func NewOrderService() *OrderService {
    return &OrderService{
        userService: service.LazyLoad[*UserService]("user-service"),
    }
}

func (s *OrderService) CreateOrder(userID int) {
    user := s.userService.Get() // Auto-loads on first access
    // ...
}

📖 See: Service, lokstra_registry

Calling Remote Services

import "github.com/primadi/lokstra/api_client"

client := api_client.NewClientRouter("https://api.example.com")

// Convention-based call
user, err := api_client.FetchAndCast[*User](client, "/users/123")

// With options
users, err := api_client.FetchAndCast[[]User](client, "/users",
    api_client.WithMethod("GET"),
    api_client.WithQuery(map[string]string{"status": "active"}),
)

📖 See: API Client, Client Router

Using Middleware

import "github.com/primadi/lokstra"
import _ "github.com/primadi/lokstra/middleware/cors"

router := lokstra.NewRouter("api")

// Apply middleware globally
router.Use("cors") // Middleware name from config/registry

// Apply to specific route
router.GET("/users", getUsersHandler, "logger")

// Apply to route group
admin := router.Group("/admin")
admin.Use("logger")
admin.GET("/users", listUsers)

📖 See: Router, Middleware

Configuration-Driven Deployment

# config.yaml
service-definitions:
  user-service:
    type: user-service-factory
    depends-on: [db-service]

external-service-definitions:
  payment-gateway:
    url: "https://payment.example.com"
    type: payment-service-remote-factory

deployments:
  production:
    servers:
      api:
        base-url: "https://api.example.com"
        addr: ":8080"
        published-services:
          - user-service

import "github.com/primadi/lokstra/core/deploy"

// Load config
server, err := deploy.LoadFromYamlFile("config.yaml", "production", "api")
server.Run(30 * time.Second)

📖 See: Configuration, Schema

📖 Documentation Conventions

Signature Format

func FunctionName(param1 Type1, param2 Type2) ReturnType

Type Definitions

type TypeName struct {
    Field1 Type1 // Description
    Field2 Type2 // Description
}

Generic Functions

func GenericFunction[T any](param T) T

Variadic Parameters

func VariadicFunction(items ...Item)

Functional Options

func NewThing(opts ...Option) *Thing

🔍 Finding What You Need

By Category

By Use Case

💡 Tips

IDE Support

Enable VS Code YAML validation:

# yaml-language-server: $schema=https://primadi.github.io/lokstra/schema/lokstra.schema.json

Godoc

Browse complete package documentation:

go doc github.com/primadi/lokstra
go doc github.com/primadi/lokstra/core/router

Examples

Every section links to working examples in the main documentation.

🔗 Related Documentation

Last Updated: {{ date }}
Lokstra Version: {{ version }}