Building a Versioned API with Chi in Go

In today’s rapidly evolving software landscape, building maintainable and scalable APIs is crucial. When developing APIs, version management becomes essential as your application grows and changes. Let’s explore how to implement a versioned API using Chi, a lightweight and powerful router for Go.

Why Chi?

Chi has gained popularity among Go developers for its simplicity and flexibility. It’s lightweight yet feature-rich, making it perfect for building RESTful APIs. One of its strongest points is the router’s middleware system, which we’ll leverage for API versioning.

Setting Up the Project

First, let’s create a basic project structure and install Chi. Our focus will be on organizing routes and handlers in a way that makes version management straightforward and maintainable.

go mod init api-versioning
go get github.com/go-chi/chi/v5

Implementing API Versioning

There are several approaches to API versioning, but we’ll implement URL-based versioning as it’s explicit and easy to understand. Here’s how we can structure our application:

package main

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

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

    // Mount v1 routes
    r.Mount("/api/v1", v1Router())

    // Mount v2 routes
    r.Mount("/api/v2", v2Router())

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

func v1Router() http.Handler {
    r := chi.NewRouter()

    r.Get("/users", v1GetUsers)
    r.Post("/users", v1CreateUser)

    return r
}

func v2Router() http.Handler {
    r := chi.NewRouter()

    r.Get("/users", v2GetUsers)
    r.Post("/users", v2CreateUser)

    return r
}

Best Practices for Version Management

1. Semantic Versioning: Follow semantic versioning principles when deciding to create a new API version
2. Documentation: Maintain clear documentation for each version
3. Deprecation Strategy: Implement a clear deprecation strategy for older versions
4. Backward Compatibility: Ensure changes don’t break existing client applications
5. Version Sunset Planning: Plan the lifecycle of each API version from the start

Advanced Features

Let’s enhance our versioned API with some advanced features:

func middlewareVersion(version string) func(next http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            w.Header().Set("API-Version", version)
            next.ServeHTTP(w, r)
        })
    }
}

This middleware adds version information to response headers, helping clients track which API version they’re using.

Conclusion

Building a versioned API with Chi gives us the flexibility to evolve our API while maintaining backward compatibility. The router’s intuitive design makes it easy to organize and maintain different versions of our endpoints, ensuring a smooth experience for both developers and API consumers.