REST Services

Humus REST services provide a complete framework for building OpenAPI-compliant HTTP APIs with automatic schema generation, type-safe handlers, and built-in observability.

Overview

REST services in Humus are built on:

• chi - Fast, lightweight HTTP router
• OpenAPI 3.0 - Automatic API documentation
• Type Safety - Compile-time type checking for requests and responses
• OpenTelemetry - Automatic tracing and metrics

Quick Start

package main

import (
    "context"
    "net/http"

    "github.com/z5labs/humus/rest"
)

type Config struct {
    rest.Config `config:",squash"`
}

type HelloResponse struct {
    Message string `json:"message"`
}

func main() {
    rest.Run(rest.YamlSource("config.yaml"), Init)
}

func Init(ctx context.Context, cfg Config) (*rest.Api, error) {
    handler := rest.ProducerFunc[HelloResponse](func(ctx context.Context) (*HelloResponse, error) {
        return &HelloResponse{Message: "Hello, World!"}, nil
    })

    api := rest.NewApi(
        "Hello Service",
        "1.0.0",
        rest.Handle(
            http.MethodGet,
            rest.BasePath("/hello"),
            rest.ProduceJson(handler),
        ),
    )
    return api, nil
}

Core Components

rest.Api

The main API object that combines:

• HTTP router (chi)
• OpenAPI spec generator
• Health check endpoints
• Middleware management

RPC Pattern

Type-safe handler abstraction in the rest package:

• rest.Handler[Req, Resp] - Business logic interface
• Request deserialization (JSON, XML, etc.)
• Response serialization
• OpenAPI schema generation

Path Building

Flexible path definition:

• Static paths: /users
• Path parameters: /users/{id}
• Nested paths: /users/{id}/posts/{postId}

Built-in Endpoints

Every REST service automatically includes:

• GET /openapi.json - OpenAPI 3.0 specification
• GET /health/liveness - Liveness probe
• GET /health/readiness - Readiness probe

What You’ll Learn

This section covers:

• Quick Start - Build your first REST API
• Handler Helpers - Type-safe handlers and serialization
• Routing - Paths and parameters
• Authentication - JWT, API keys, and security
• Interceptors - Operation-level request/response processing
• Error Handling - Custom error responses
• OpenAPI - Working with generated specs
• Health Checks - Monitoring service health

Next Steps

Start with the Quick Start Guide to build your first REST service.