# Go

A Go 1.25 REST API starter built only on net/http and log/slog, for developers who want an API with no framework and no third-party modules. It includes / and /health routes, per-request structured logs, graceful shutdown, table-driven httptest tests and a multi-stage Dockerfile.

- Framework: Go (Go)
- Category: Starters / REST APIs
- Creates: a server app
- Plan: Free
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/rest-apis/go-api-starter
- Updated: 2026-11-21

## Features

- No dependencies: go.mod has no require lines and there is no go.sum
- GET / returns a welcome message, a version and the endpoint list; GET /health returns RFC 3339 time and uptime
- Middleware writes one log/slog JSON line per request with method, path, status and duration
- Graceful shutdown on SIGTERM or Ctrl+C with a 10 second drain, and a 10 second ReadHeaderTimeout
- Table-driven route tests with net/http/httptest, run with go vet by make test
- Multi-stage Dockerfile builds on golang:1.25-alpine and runs the binary as nobody on Alpine
- make build writes a static binary to bin/server with CGO disabled
- Code under internal/ keeps config and the HTTP layer private to the module; listens on PORT, default 8080

## What you need

- Free plan: it runs as a server app, and the Free plan includes 3 server apps
- To run it locally: Go 1.25 or newer; make runs the run, test and build shortcuts
- Optional: Docker, to build and run the container image yourself
- No API keys: it starts with nothing to configure

## About

main.go only wires things together: it loads PORT from internal/config, builds the handler from internal/server and runs an http.Server until a stop signal arrives. Routing uses the standard ServeMux, so adding a route with a method and path wildcard, such as GET /items/{id} read with r.PathValue, needs no router package. The trade-off is that you write your own JSON helpers and validation, which is the point of a zero-dependency start. On Light Cloud the image is built from the Dockerfile and run as a container on the platform's PORT, and every push to your copy rebuilds it.

## Questions

### How do I add a route with path parameters in Go net/http?

Since Go 1.22 the standard ServeMux matches methods and wildcards. Register mux.HandleFunc("GET /items/{id}", h.getItem) in internal/server/server.go and read the value with r.PathValue("id").

### Do I need Gin, Echo or Fiber for a Go REST API?

Not for a JSON API of this size: net/http handles routing and middleware is a function wrapping an http.Handler. Reach for a framework when you want its request binding, validation or middleware collection.

### How do I add an environment variable to this Go app?

Add a field to Config in internal/config/config.go and read it in Load with getenv("NAME", "default"). Put a local value in .env, which make run loads.

### Can I run this Go API on any Docker host?

Yes. There is no Light Cloud code in it: docker build and docker run the Dockerfile on any container platform, or copy the binary from make build to a server and start it with PORT set.

### Is there a Go starter with a PostgreSQL database?

This one has no database. The gin-postgresql-crud-api template shows a Go app on PostgreSQL with pgx, reading the DB_HOST, DB_NAME, DB_USER and DB_PASSWORD variables Light Cloud sets.
