Scaffolding the API

grit new my-api --api walkthrough.

5 mineasy

Welcome to Building a Go API. Goal of this chapter: scaffold an API-only project, identify every file, get it serving requests. This first lesson is the scaffold itself — 5 minutes, one command, you're ready.

This course assumes you can read Go syntax (structs, methods, error handling) and run a Docker container locally. If either is shaky, skim the primers first — they take 15 minutes each.

Go (Golang) primer

Variables, structs, pointers, slices, maps, interfaces, goroutines.

Docker primer

Images, containers, volumes, networks, docker compose.

The command

Terminal

$grit new bench-api --api

Pick the project name (anything kebab-case works). The --api flag tells Grit you want the headless Go backend kit — no apps/web, no apps/admin, just the Go API.

What you get

You'll see the standard checklist run:

✓ Created bench-api/
✓ Wrote 42 files
✓ Initialized go module
✓ Generated random secrets (JWT_SECRET, SENTINEL_*, PULSE_*)

Next steps:
    cd bench-api
    docker compose up -d
    cd apps/api && go run cmd/server/main.go

Surprise: even the API-only kit is structured as a monorepo. The Go code lives at apps/api/, not the project root. This is so you can later add a frontend by dropping it next to apps/api/ without moving files.

The kit's shape at a glance

bench-api/

bench-api/
├── apps/
│   └── api/                    The Go API lives here
│       ├── cmd/server/main.go  Entry point
│       ├── internal/           All Go code
│       ├── .air.toml           Hot-reload config
│       ├── go.mod
│       └── Dockerfile
├── docker-compose.yml          Postgres + Redis + MinIO + Mailhog
├── docker-compose.prod.yml
├── .env                        Generated with random secrets
├── .env.example
├── grit.json
└── README.md

What didn't get scaffolded

No apps/web/ — no public Next.js site
No apps/admin/ — no Filament-style admin panel
No packages/shared/ — no Zod schemas + TS types
No turbo.json, pnpm-workspace.yaml — Go-only deps

Everything else from the Concepts course — random JWT secret, Sentinel + Pulse pre-configured, SQLite support out of the box — still ships.

Quick check

You scaffolded with `--api` but then decided you want an admin panel. What's the cleanest path?

Try it

Scaffold bench-api with the API-only kit. Then run ls -la bench-api (Mac/Linux) or dir bench-api (Windows) and paste the output in notes.md.

Note: do not use cd apps/api yet — we'll tour the structure in the next lesson before running anything.

What's next

Files are on disk. Next lesson — the tour. We open apps/api/internal/ and walk every folder, naming the responsibility of each.

Spot a typo? Have an idea?

Help us improve this lesson. One click opens a GitHub issue with the lesson URL pre-filled — suggest clearer wording, report a bug, or request more depth. The course keeps improving thanks to learners like you.

Suggest an improvement on GitHub

Next lesson