Go libraries for API servers that stay simple as they grow

Why simple API code gets messy fast

Most API code does not start messy. It starts small.

You add three routes, one database call, and a health check. A week later, the service has auth, rate limits, request IDs, a webhook, and a second group of internal endpoints. The code still works, but the shape of the app gets harder to see.

Routing is often the first place that drifts. One endpoint turns into versioned routes, admin paths, and special cases for webhooks or internal tools. If route setup lives in too many files, nobody can glance at the app and understand what the API actually exposes.

Then repeated handler code creeps in. Logging, auth checks, CORS headers, panic recovery, and response formatting often start inside one handler because it feels quick. Soon that same setup appears in ten handlers with slight differences. One route logs the user ID. Another forgets. One sets CORS headers correctly. Another breaks preflight requests.

Validation usually follows the same pattern. A field gets checked in the handler, checked again in the service layer, and mocked differently in tests. After a while, nobody knows which rule is real. Changing one field means touching three places and hoping the tests still match production.

Config causes quieter damage. A service begins with a few env vars. Before long, it has feature flags, timeout values, database settings, and API tokens pulled from globals or ad hoc lookups. When config lives everywhere, local runs, tests, and production stop behaving the same way.

Readable Go services do not stay clean by accident. They stay clean when each concern has one clear home.

The 12 libraries in this comparison

Small services rarely fall apart on day one. They get awkward when auth, rate limits, validation, and config rules start piling up. That is why this comparison mixes very small packages with a few larger ones that can still save time early.

A toy CRUD app can make almost any library look neat. Real services expose the tradeoffs later, when you need to change a route, add a new header rule, or explain a validation error without turning a handler into a wall of code.

For routing, chi and httprouter stay close to the standard library. Gin and Echo give you more built-in helpers, which can speed up early work but also shape the way the whole service reads. For middleware, alice keeps chaining simple, rs/cors handles browser rules cleanly, and go-chi/httprate adds rate limiting without taking over the app. For validation, go-playground/validator works well for struct-tag driven requests, while ozzo-validation keeps rules in Go code, which often reads better once checks depend on other fields. For config, caarlos0/env and cleanenv keep environment-based setup plain, while koanf is the better fit when settings come from several places.

No library wins every time. The useful question is simpler: which ones still look clear after real features land and the service has to live for a year, not a weekend?

What to judge before you add one

Start with learning cost. A package can save twenty lines and still make the code worse if every teammate has to learn a new request model, special error flow, or custom way to register routes.

Plain net/http types are a good reality check. If handlers still accept http.ResponseWriter and *http.Request, the package is usually easier to replace later. Once a library wraps everything in its own context or handler shape, the code drifts away from standard Go and gets harder to scan.

Tests expose the truth fast. Good packages let you build a request with httptest.NewRequest, pass it to a handler, and inspect the response. If a basic test needs a full app container, global setup, and half the service booted first, that package carries more weight than it first seemed.

Watch for hidden behavior. Global state, default singletons, init() side effects, and tags that do too much are where clutter starts. Simple JSON tags are fine. Tags that validate, map config, set defaults, and change runtime behavior all at once usually age badly.

It also helps to keep each tool in its own lane. A router should route. A validator should validate. A config package should load config. When one library tries to do all of it, a small service stops feeling small.

A package usually earns its place if the team can learn it quickly, test one handler without heavy setup, avoid hidden globals, and keep business logic separate from the library itself.

Routers that stay out of the way

A router should make request handling easier to follow, not turn a small API into a framework project. This choice often sets the tone for the rest of the codebase.

chi is the safest default for most teams. It keeps the familiar net/http style, so handlers, tests, and middleware still feel like normal Go. Route groups are easy to read, and small middleware stacks fit naturally.

httprouter is a good fit when you want the smallest possible surface area and care about speed. It does less, and that is the point. For a tiny service, that can feel refreshingly clean. The tradeoff shows up later, when the API needs richer request handling and you have to wire more pieces yourself.

Gin works well for teams that want more built in from the start. Binding, rendering, and helper methods save time. That convenience is real, but Gin also shapes how handlers look. After a while, the code reads more like Gin code than plain Go.

Echo sits close to Gin, but its API often feels a bit tighter. Many teams like it because common tasks take fewer lines. If that style clicks, day-to-day work can feel smooth.

The short version is simple. Pick chi if you want plain Go with just enough routing help. Pick httprouter if you want minimal and fast. Pick Gin if built-in helpers save your team real time. Pick Echo if you want a compact API and do not mind leaning into its style.

After you choose, stay consistent. Mixing router patterns inside one service makes code review slower and bug fixes more annoying than they should be.

Middleware helpers that cut repeated code

Repeated code often piles up around handlers, not inside them. One route adds a request ID, another logs timing, a third checks auth. Soon every endpoint has the same setup wrapped around different business rules, and the useful part gets buried.

alice fixes that with very little ceremony. You build the middleware chain once and apply it where needed. That keeps request flow in one place and makes changes easier to review.

Order matters. A clean chain usually puts request IDs and logging near the top, CORS before the browser gets blocked, rate limiting before expensive work, and auth before the handler runs.

If a browser app calls your API, rs/cors is a practical add-on. It keeps CORS rules out of handlers and in one place. Keep the policy narrow. Allow the origins and methods you actually use instead of throwing in a wildcard by habit.

For public endpoints, go-chi/httprate is a good lightweight choice. It can stop bursts before they hit your database or queue. That matters more than people think, especially for small services where a few noisy clients can eat a lot of capacity.

The main rule here is boring and useful: keep auth, logging, request IDs, CORS, and rate limits out of business logic. A handler should read like one unit of work. Parse the request, call the service, return the response.

Validators that keep rules close to requests

If your handler opens with ten if statements, validation is in the wrong place. Check the request right after decoding it. Then the rest of the handler can focus on the actual action.

go-playground/validator works well when request structs already match the shape of the API. Tags like required, email, min, and oneof keep common rules close to the fields users send. That fits simple requests such as signup, login, or a create project form. The downside comes later. Once tag strings get long, they get harder to read and harder to review.

ozzo-validation is often the better choice when rules need names, conditions, or a bit of business logic. Writing validation in Go code is easier to follow than cramming everything into tags. A reviewer can open one function and understand the rule set quickly.

Keep cross-field checks in one place. If end_date must be after start_date, or a request must include either email or phone, put that rule in one Validate() method or one validator function. Tests stay shorter because every rule has one home.

Error messages should help people fix the request fast. Return field errors like email: must be a valid email address or age: must be 18 or more. Skip vague replies like invalid input, and do not dump raw validator output into the response.

Config tools that stay boring

Config should be the dullest part of the service. If config gets clever, the rest of the app gets harder to reason about. Good config answers three questions quickly: what can be set, where it comes from, and which value wins.

caarlos0/env is a good fit when environment variables already cover the whole app. It works well for small services, containers, and deployments where runtime config is the only source you need.

cleanenv fits teams that want env parsing plus a small config file option without much ceremony. That can help in local development, where a tiny file is convenient, while production still relies on env vars.

koanf makes sense when settings come from several places and you need clear precedence, such as defaults first, file second, and env last. It is flexible, but that flexibility adds code and mental overhead, so it is better to choose it for a real reason.

Keep defaults near the config struct. That is where people will look first. If timeout values live in one package, ports in another, and feature flags in a startup helper, even a small change turns into a scavenger hunt.

Load config once at startup, validate it, and fail fast if something is missing or malformed. Then pass typed values down to the parts that need them. A database client should receive typed database config, not read raw env vars on its own.

Boring config saves time. It also makes later cleanup much easier when the app grows new workers, queues, or external integrations.

A small service example

A contact form service sounds tiny. Then requests start coming from a website, a mobile app, a spam bot, and a sales team that wants every lead pushed into a CRM. Without some structure, even that small API turns into a pile of handlers, repeated checks, and settings scattered across the codebase.

A clean starting stack for this kind of service is chi for routing, alice for middleware, go-playground/validator for request checks, and caarlos0/env for settings. That combination stays readable after the first few features because each piece has a narrow job.

One handler can accept the contact form, validate fields like name, email, and message, then pass a tidy request object to a service layer. That service decides what to store and when to send data to the CRM. The handler stays short. Business rules stay out of HTTP code. Future changes hurt less.

You do not need every extra package on day one. Add rs/cors only if a browser app calls the API from another origin. If the site posts from the same origin, skip it. Add httprate on public endpoints that invite bursts or abuse, such as a contact form or newsletter signup. Internal admin routes usually do not need it.

The folder layout can stay small too. A simple split like cmd for the app entry point, internal/http for routes and handlers, internal/service for business logic, internal/store for database access, and internal/config for env parsing is enough for a lot longer than most teams expect.

That kind of lean structure is often all a growing product needs at first. Oleg Sotnikov at oleg.is works with startups and smaller companies on this exact problem: keeping architecture, infra, and delivery simple enough to move fast without letting early shortcuts harden into mess.

Choose your stack in steps

Most teams add libraries before they feel real pain. That sounds careful, but it often makes a small service harder to read.

A better approach is to let the code tell you what it needs. Start with one plain handler in net/http. Write request parsing, the response, and the error path yourself. Then look at what actually feels repetitive.

If route params, nested paths, or route groups start to feel awkward, add a router. If the same request flow keeps repeating, add one middleware helper. If validation rules spread across handlers, pick one validation style and use it everywhere. Add a config tool only when env loading starts to repeat across files or packages.

The order matters. If you add five middleware packages at once, you will spend more time tracing request flow than building endpoints. The same goes for validation. One clear pattern beats three clever ones.

Review the stack early, after three endpoints rather than thirty. By then, you can spot real friction without being stuck with a pile of wrappers.

A service with login, profile, and health-check routes is already enough to test your choices. If the code still reads cleanly after that, the stack is probably in a good place.

Mistakes that add clutter

Most Go services get messy in small steps, not from one dramatic mistake. One week you add a router helper. The next week you drop auth checks into a handler. A month later, nobody can tell where request rules live.

One common problem is mixing Gin handlers with plain net/http handlers in the same codebase. Both styles work, but now the team has two ways to read params, write responses, and attach middleware. A fix that should take ten minutes turns into a hunt through competing patterns.

The giant handler function causes even more trouble. If one function parses JSON, validates fields, checks auth, loads records, writes to the database, and formats the response, nobody wants to touch it. Keep the handler narrow. Let it deal with input and output. Keep validation close to the request type. Move business logic into a service or package of its own.

Some clutter starts with tools that solve a much bigger problem than you actually have. A tiny API does not need a config system with file watchers, deep merge rules, and several override layers. The same goes for API libraries in general. If a package adds concepts your team will never use, every edit gets slower.

Package globals make things worse. Global config and a global logger feel convenient at first, but they hide dependencies and make tests awkward. Pass them in explicitly so each package says what it needs.

Middleware is another quiet trap. Teams pile on request IDs, wrappers, metrics hooks, audit hooks, and auth helpers because they all sound useful. If nobody can explain why a middleware exists, remove it. Dead code in the request path still wastes time every time you debug a request.

Quick checks before you settle on a stack

A clean stack feels obvious when one request fails. Open one endpoint and trace the path from router to handler to validation to response. If a new teammate cannot follow that path in five minutes, the service is already too tangled.

Testing reveals the same problem quickly. You should be able to call one handler with a fake request and a stubbed dependency. If the test needs the full app, the config loader, background jobs, and the entire middleware chain just to check one JSON response, the package boundaries are weak.

Error messages are another good signal. A bad email field should name the field and explain the rule it broke. A missing setting should tell you which env var is absent. Plain, clear errors are usually a better sign than clever abstractions.

A solid stack usually has a few traits in common: one package owns one job, business logic does not depend on router or validator types, swapping a library later mostly changes glue code, and defaults fit on one screen. If the stack cannot meet those tests, it is probably doing too much.

The best setup is often a little boring. Boring code is easier to test, easier to hand off, and much easier to fix on a bad Friday afternoon.

If the service keeps growing

Growth usually breaks the parts nobody wrote down. One service can survive on team memory. Two services usually cannot.

Before you start the next service, write a short default for routing, request validation, error responses, and config layout. Keep it plain. One page is often enough. It should answer basic questions: which router is the default, where validation rules live, what error shape clients get, how config loads across environments, and which middleware is allowed by default.

That small document saves a lot of cleanup later. Teams that skip it often end up with three ways to parse params, two error formats, and env vars named in five different styles.

Do not turn your first decent stack into a template too early. Reuse it only after it survives real change: a new endpoint group, a change in auth rules, one awkward request type, and at least one production bug. If the code still feels readable after that, it is probably worth copying.

After the first production week, stop guessing and inspect the service. Check logs for noisy errors, review rate limits, and look at the config shape. If a small service already needs too many flags or too many exception paths, the problem is usually design, not traffic.

If the API connects to a larger product, a short outside review can save months of drift. Someone with broad product and infrastructure experience, like Oleg Sotnikov, can often spot weak boundaries, deployment friction, and cost issues before they turn into permanent habits.

Simple libraries still need simple team rules. Write them down, test them under real change, and keep only the parts your team still likes using after a rough week in production.