Building Your Personal Comedian API: A Web Service Tutorial Using Go and Chi

The problem with most "getting started" tutorials is that they teach you how to build things that are not interesting. Another TODO list. Another CRUD app you will abandon halfway through.

Let us build something different: a web service in Go that generates puns, jokes, proverbs, and quotes using Google's Gemini AI. It is simple enough to finish in an afternoon but real enough to teach you how actual web services work. We will include practical practices that will serve you well when you build more serious applications.

Think of this as building your personal comedian that lives on the internet and never runs out of material.

What We Are Actually Building

Before we write a single line of code, here is what we are aiming for. By the end of this tutorial, you will have a web service with endpoints like:

• GET /joke - Returns a random joke
• GET /pun - Returns a pun (the dad-joke kind)
• GET /quote - Returns an inspirational quote
• GET /proverb - Returns a proverb or piece of wisdom

Each endpoint talks to Gemini AI and returns a JSON response.

Here is an example response:

{
  "content": "Why don't scientists trust atoms? Because they make up everything!",
  "type": "joke",
  "timestamp": "2024-03-15T10:30:00Z"
}

Setting Up: The Foundation

First, ensure you have Go installed.

Create a new project:

mkdir comedian-api
cd comedian-api
go mod init comedian-api

A Note on Module Names: The import paths used in your code (e.g., comedian-api/ai) must match the module path declared in go.mod. If you initialise the module with a different name (e.g., github.com/you/comedian-api), then your local imports must use that name instead.

Now we need two dependencies: Chi (our routing library) and the Gemini AI SDK:

go get github.com/go-chi/chi/v5
go get github.com/google/generative-ai-go/genai
go get google.golang.org/api/option

You will also need a Gemini API key. Obtain one from Google AI Studio (ai.google.dev), save it securely, and do not commit it to source control. We discuss safer handling below.

The Simplest Thing That Could Possibly Work

Start with the basics to see Chi in action:

package main

import (
    "net/http"
    "github.com/go-chi/chi/v5"
)

func main() {
    r := chi.NewRouter()

    r.Get("/joke", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("This will be a joke soon, I promise"))
    })

    http.ListenAndServe(":8080", r)
}

Run it with go run main.go, and open your browser to http://localhost:8080/joke. Chi is straightforward: create a router with chi.NewRouter(), register routes with r.Get(), and it matches incoming requests to the handlers. Chi sits on top of Go's standard net/http.

Making It Actually Talk to Gemini

We implement the AI client in a dedicated package to keep generation logic separate and make future replacements or tests easier.

Create ai/client.go:

// ai/client.go
package ai

import (
    "context"
    "fmt"

    "github.com/google/generative-ai-go/genai"
    "google.golang.org/api/option"
)

type Client struct {
    model *genai.GenerativeModel
}

func NewClient(apiKey string) (*Client, error) {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, option.WithAPIKey(apiKey))
    if err != nil {
        return nil, fmt.Errorf("failed to create AI client: %w", err)
    }

    model := client.GenerativeModel("gemini-1.5-flash")
    return &Client{model: model}, nil
}

func (c *Client) GenerateJoke(ctx context.Context) (string, error) {
    prompt := "Generate a short, funny joke. Just the joke, no explanation."

    resp, err := c.model.GenerateContent(ctx, genai.Text(prompt))
    if err != nil {
        return "", fmt.Errorf("failed to generate joke: %w", err)
    }

    if len(resp.Candidates) == 0 || len(resp.Candidates[0].Content.Parts) == 0 {
        return "", fmt.Errorf("empty response from AI")
    }

    return fmt.Sprintf("%v", resp.Candidates[0].Content.Parts[0]), nil
}

This file encapsulates Gemini calls. Note the error wrapping and checks for empty responses, which make failures explicit and easier to diagnose.

Building the Handler Layer

Handlers respond to HTTP requests. Group handlers together on a struct to pass shared dependencies (AI client, logger) explicitly.

Create handlers/handlers.go:

// handlers/handlers.go
package handlers

import (
    "context"
    "encoding/json"
    "log"
    "net/http"
    "time"

    "comedian-api/ai"
)

type Response struct {
    Content   string    `json:"content"`
    Type      string    `json:"type"`
    Timestamp time.Time `json:"timestamp"`
}

type ErrorResponse struct {
    Error     string    `json:"error"`
    Timestamp time.Time `json:"timestamp"`
}

type Handler struct {
    aiClient *ai.Client
    logger   *log.Logger
}

func NewHandler(aiClient *ai.Client, logger *log.Logger) *Handler {
    return &Handler{
        aiClient: aiClient,
        logger:   logger,
    }
}

func (h *Handler) HandleJoke(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    joke, err := h.aiClient.GenerateJoke(ctx)
    if err != nil {
        h.logger.Printf("Error generating joke: %v", err)
        h.respondWithError(w, "Failed to generate joke", http.StatusInternalServerError)
        return
    }

    h.respondWithJSON(w, Response{
        Content:   joke,
        Type:      "joke",
        Timestamp: time.Now(),
    })
}

func (h *Handler) respondWithJSON(w http.ResponseWriter, data interface{}) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(data)
}

func (h *Handler) respondWithError(w http.ResponseWriter, message string, code int) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(ErrorResponse{
        Error:     message,
        Timestamp: time.Now(),
    })
}

Struct Tags: The backquoted tags, such as `json:"content"`, instruct Go's encoding/json package how to serialise struct fields. json:"content" ensures the JSON key is content (lowercase) rather than the Go field name Content.

This handler pattern keeps your code testable and modular by explicitly passing shared dependencies via the Handler struct.

Putting It All Together

Wire everything in main.go, including environment variable setup, Chi middleware, and graceful shutdown:

// main.go
package main

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

    "comedian-api/ai"
    "comedian-api/handlers"
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)

func main() {
    logger := log.New(os.Stdout, "[COMEDIAN-API] ", log.LstdFlags)

    apiKey := os.Getenv("GEMINI_API_KEY")
    if apiKey == "" {
        logger.Fatal("GEMINI_API_KEY environment variable not set")
    }

    aiClient, err := ai.NewClient(apiKey)
    if err != nil {
        logger.Fatalf("Failed to create AI client: %v", err)
    }

    h := handlers.NewHandler(aiClient, logger)

    r := chi.NewRouter()
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)

    r.Get("/joke", h.HandleJoke)
    r.Get("/pun", h.HandlePun)       // add when implemented
    r.Get("/quote", h.HandleQuote)   // add when implemented
    r.Get("/proverb", h.HandleProverb) // add when implemented

    srv := &http.Server{
        Addr:    ":8080",
        Handler: r,
    }

    go func() {
        logger.Println("Starting server on :8080")
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            logger.Fatalf("Server failed: %v", err)
        }
    }()

    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit

    logger.Println("Shutting down server...")

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Fatalf("Server forced to shutdown: %v", err)
    }

    logger.Println("Server stopped")
}

The graceful shutdown logic uses os/signal and srv.Shutdown to ensure in-flight requests are completed before the process exits.

Adding More Endpoints

Add methods to the AI client for puns, quotes, and proverbs, following the same pattern as GenerateJoke:

// ai/client.go (additional methods)
func (c *Client) GeneratePun(ctx context.Context) (string, error) {
    prompt := "Generate a short, clever pun. Just the pun, no explanation."
    // same pattern as GenerateJoke
}

func (c *Client) GenerateQuote(ctx context.Context) (string, error) {
    prompt := "Generate an inspirational or thought-provoking quote. Just the quote."
    // same pattern as GenerateJoke
}

func (c *Client) GenerateProverb(ctx context.Context) (string, error) {
    prompt := "Generate a wise proverb or saying. Just the proverb."
    // same pattern as GenerateJoke
}

Then, add corresponding handler methods in handlers/handlers.go mirroring the HandleJoke pattern and register the routes in main.go:

r.Get("/pun", h.HandlePun)
r.Get("/quote", h.HandleQuote)
r.Get("/proverb", h.HandleProverb)

If you prefer versioned APIs, use r.Route to group endpoints:

r.Route("/api/v1", func(r chi.Router) {
    r.Get("/joke", h.HandleJoke)
    r.Get("/pun", h.HandlePun)
    r.Get("/quote", h.HandleQuote)
    r.Get("/proverb", h.HandleProverb)
})

By now, your project should look like this:

comedian-api/
├── main.go
├── ai/
│   └── client.go
├── handlers/
│   └── handlers.go
└── go.mod