Rivaas Router Examples

Pure router and middleware feature demonstrations.

No domain logic here - these examples focus solely on router and middleware capabilities.

For complete, production-ready applications with business logic, see app/examples/.

📚 Examples Overview

The examples are organized in a progressive learning path:

1. Hello World

Start here! The simplest possible Rivaas application.

cd 01-hello-world && go run main.go
curl http://localhost:8080/

Learn: Basic router setup, simple JSON responses

2. Routing

Routes, parameters, HTTP methods, and route groups.

cd 02-routing && go run main.go
curl http://localhost:8080/users/123

Learn: Path parameters, route groups, nested groups, HTTP methods (GET, POST, PUT, DELETE)

3. Complete REST API

Production-ready CRUD API with validation and error handling.

cd 03-complete-rest-api && go run main.go
curl http://localhost:8080/api/v1/users
curl -X POST http://localhost:8080/api/v1/users -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'

Learn:

Request binding (Bind, BindQuery, BindParams)
Structured error responses with proper HTTP codes
Input validation patterns
Business logic separation
Nested resources (users/:id/posts)

4. Middleware Stack

Complete middleware guide for production.

cd 04-middleware-stack && go run main.go
curl http://localhost:8080/api/data
curl -H 'Authorization: Bearer token123' http://localhost:8080/protected/secret

Learn:

Common middleware (auth, logging, recovery, CORS)
Middleware patterns (global, group, per-route, conditional)
Custom middleware creation with configuration
Middleware ordering and composition
Rate limiting, request tracking, validation

5. Advanced Routing

Advanced features for mature APIs.

cd 05-advanced-routing && go run main.go
curl http://localhost:8080/users/123           # ✓ Valid (numeric)
curl http://localhost:8080/users/abc           # ✗ Invalid (not numeric)
curl -H "API-Version: v1" http://localhost:8080/users
curl http://localhost:8080/files/static/image.jpg

Learn:

Route constraints (UUID, numeric, alpha, regex)
Proper HTTP method semantics (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS)
Wildcard routes for file serving
Route introspection

6. Content and Rendering

Request handling and response rendering.

cd 06-content-and-rendering && go run main.go
curl -H "Accept: application/json" http://localhost:8080/api/user
curl http://localhost:8080/json/pure
curl http://localhost:8080/benchmark?format=pure

Learn:

Content negotiation (Accept headers for JSON/XML/HTML)
Rendering methods (JSON, PureJSON, YAML, etc.)
Performance comparisons (PureJSON 35% faster, Data 98% faster)
Context helpers (Query, Param, Header, Cookie, ClientIP)
Streaming responses with DataFromReader
JSONP for legacy support

7. API Versioning

Comprehensive API versioning strategies and migration patterns.

cd 07-versioning && go run main.go
curl -H 'API-Version: v2' http://localhost:8080/users
curl 'http://localhost:8080/users?version=v2'
curl http://localhost:8080/v2/users

Learn:

All versioning methods (header, query, path, accept)
Version-specific handlers and routes
Migration patterns (v1 → v2 → v3)
Deprecation warnings and sunset dates
Version validation and observability
Algorithm details
Best practices for API evolution

See Also: Versioning Guide for comprehensive documentation

🚀 Quick Start

Choose an example based on what you want to learn
Navigate to the directory:
```
cd router/examples/01-hello-world
```
Run the example:
```
go run main.go
```
Test with curl (commands are shown in each example's output)

📖 Learning Path

Progressive Learning

Core Routing (Start Here)

Start with 01-hello-world to understand the basics
Move to 02-routing to learn about routes and parameters

Practical Application

Build 03-complete-rest-api for production-ready CRUD patterns
Study 04-middleware-stack for complete middleware guide

Advanced Features

Master 05-advanced-routing for constraints and HTTP methods
Explore 06-content-and-rendering for flexible response handling
Study 07-versioning for API evolution and migration patterns

🔧 Common Patterns

Creating a Router

r := router.New()

With Options

r := router.New(
    router.WithVersioning(
        router.WithHeaderVersioning("API-Version"),
        router.WithDefaultVersion("v1"),
    ),
)

Adding Routes

r.GET("/users/:id", handler)
r.POST("/users", handler)
r.PUT("/users/:id", handler)
r.DELETE("/users/:id", handler)

Route Groups

api := r.Group("/api/v1")
api.Use(authMiddleware)
api.GET("/users", listUsers)

Middleware

// Global
r.Use(logger, recovery)

// Group-specific
api.Use(authMiddleware)

// Per-route (pass middleware as arguments)
r.GET("/admin", adminMiddleware, handler)

Route Constraints

Typed constraints with OpenAPI semantics:

r.GET("/users/:id", handler).WhereInt("id")           // OpenAPI: type integer
r.GET("/entities/:uuid", handler).WhereUUID("uuid")   // OpenAPI: format uuid
r.GET("/files/:name", handler).WhereRegex("name", `[a-zA-Z0-9._-]+`)

API Versioning

r := router.New(
    router.WithVersioning(
        router.WithHeaderVersioning("API-Version"),
        router.WithQueryVersioning("version"),
        router.WithDefaultVersion("v1"),
    ),
)

// Version-specific routes
v1 := r.Version("v1")
v1.GET("/users", getUsersV1)

v2 := r.Version("v2")
v2.GET("/users", getUsersV2)

Wildcard Routes

// Wildcard routes
r.GET("/files/*", fileHandler)
r.GET("/static/*", staticHandler)

// Access in handler
func fileHandler(c *router.Context) {
    filepath := c.Param("filepath")
    // Handle file request
}

Request Binding

// Bind request body
type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

var req CreateUserRequest
if err := c.Bind(&req); err != nil {
    c.JSON(http.StatusBadRequest, errorResponse)
    return
}

// Bind query parameters
type ListParams struct {
    Page     int `query:"page"`
    PageSize int `query:"page_size"`
}

var params ListParams
c.BindQuery(&params)

// Bind path parameters
type PathParams struct {
    ID int `params:"id"`
}

var params PathParams
c.BindParams(&params)

Structured Error Responses

type APIError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
    Details any    `json:"details,omitempty"`
    Path    string `json:"path,omitempty"`
}

c.JSON(http.StatusNotFound, APIError{
    Code:    "USER_NOT_FOUND",
    Message: "User not found",
    Path:    c.Request.URL.Path,
})

🧪 Testing Examples

Each example includes curl commands in its output. Generally:

# Run the example
go run main.go

# In another terminal, test it
curl http://localhost:8080/

🎯 What's Here vs. What's in `app/`

Use `router/examples` to learn

✅ How routing works
✅ How to use middleware
✅ Router features and APIs
✅ Request/response handling
✅ Pure router capabilities

Use `app/examples` for

❌ Complete applications
❌ Database integration
❌ Authentication patterns
❌ Business logic
❌ Production deployments

📝 Building Your Own

Copy a similar example as a starting point
Modify routes to match your API design
Add middleware as needed for auth, logging, etc.
Add validation with route constraints
Use versioning for API evolution
Implement wildcards for flexible routing
Handle errors with structured responses
Build custom middleware for your needs

🤝 Need Help?

Check the main README
Review similar examples
Look at the router documentation

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 The Rivaas Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rivaas Router Examples

📚 Examples Overview

1. Hello World

2. Routing

3. Complete REST API

4. Middleware Stack

5. Advanced Routing

6. Content and Rendering

7. API Versioning

🚀 Quick Start

📖 Learning Path

Progressive Learning

Core Routing (Start Here)

Practical Application

Advanced Features

🔧 Common Patterns

Creating a Router

With Options

Adding Routes

Route Groups

Middleware

Route Constraints

API Versioning

Wildcard Routes

Request Binding

Structured Error Responses

🧪 Testing Examples

🎯 What's Here vs. What's in `app/`

Use `router/examples` to learn

Use `app/examples` for

📝 Building Your Own

🤝 Need Help?

📄 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Rivaas Router Examples

📚 Examples Overview

1. Hello World

2. Routing

3. Complete REST API

4. Middleware Stack

5. Advanced Routing

6. Content and Rendering

7. API Versioning

🚀 Quick Start

📖 Learning Path

Progressive Learning

Core Routing (Start Here)

Practical Application

Advanced Features

🔧 Common Patterns

Creating a Router

With Options

Adding Routes

Route Groups

Middleware

Route Constraints

API Versioning

Wildcard Routes

Request Binding

Structured Error Responses

🧪 Testing Examples

🎯 What's Here vs. What's in app/

Use router/examples to learn

Use app/examples for

📝 Building Your Own

🤝 Need Help?

📄 License

🎯 What's Here vs. What's in `app/`

Use `router/examples` to learn

Use `app/examples` for