Blog

• Tutorials
• Getting Started with Rivaas in 5 Minutes
• Comparisons
• Engineering
• Releases

Tutorials

Getting Started with Rivaas in 5 Minutes

Most Go web frameworks make you choose between simplicity and production features. With Rivaas, you get both. In this tutorial, you’ll build a REST API with automatic OpenAPI documentation, health probes, and interactive Swagger UI — all in under 5 minutes.

Prerequisites

• Go 1.25 or later
• A terminal and your favorite editor

Step 1: Create Your Project

mkdir rivaas-quickstart && cd rivaas-quickstart
go mod init example.com/quickstart
go get rivaas.dev/app
go get rivaas.dev/openapi

Step 2: Write Your First Handler

Create main.go:

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"

    "rivaas.dev/app"
    "rivaas.dev/openapi"
)

func main() {
    a, err := app.New(
        app.WithHealthEndpoints(),
        app.WithOpenAPI(
            openapi.WithTitle("Quickstart API", "1.0.0"),
        ),
    )
    if err != nil {
        log.Fatal(err)
    }

    a.GET("/hello", func(c *app.Context) {
        c.JSON(http.StatusOK, map[string]string{
            "message": "Hello from Rivaas!",
        })
    })

    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer cancel()

    if err := a.Start(ctx); err != nil {
        log.Fatal(err)
    }
}

Step 3: Run It

go run main.go

Your API is now running on http://localhost:8080 with several endpoints ready out of the box.

Step 4: Explore the Built-in Endpoints

Rivaas gives you production-ready endpoints without any extra configuration:

Try them:

curl http://localhost:8080/hello
curl http://localhost:8080/livez
curl http://localhost:8080/openapi.json

Open http://localhost:8080/docs in your browser to see the interactive API documentation — generated automatically from your registered routes and Go types.

Step 5: Add Request Binding

Let’s make the API more interesting with typed request handling. Add this inside main(), after the GET handler:

type CreateUserRequest struct {
    Name  string `json:"name"  validate:"required"`
    Email string `json:"email" validate:"required,email"`
}

a.POST("/users", func(c *app.Context) {
    var req CreateUserRequest
    if err := c.Bind(&req); err != nil {
        return
    }

    c.JSON(http.StatusCreated, map[string]string{
        "message": "User created",
        "name":    req.Name,
    })
})

Rivaas automatically validates the request body, returns structured error messages, and updates the OpenAPI spec to include the new endpoint.

What You Get Out of the Box

With the options used above, your Rivaas application includes:

• Liveness and readiness probes at /livez and /readyz
• OpenAPI 3.1 spec generated from your registered routes and Go types
• Interactive Swagger UI at /docs
• Graceful shutdown handling SIGTERM/SIGINT
• Panic recovery middleware

Need observability? Add WithObservability() to enable structured logging, OpenTelemetry tracing, and Prometheus metrics — each configurable independently.

Next Steps

• First application — a deeper walkthrough of the full app setup
• App guide — lifecycle, middleware, and server configuration
• Binding guide — JSON, query params, path params, and validation
• OpenAPI guide — customize your auto-generated API docs

Comparisons

Engineering

Releases