Build & Deploy a REST API with Go (API-Only Masterclass)

When to Go API-Only

Not every project needs a frontend. Sometimes you just need a clean, fast API that other services or apps consume. Grit's --api flag gives you exactly that — a lean Go API with no frontend overhead.

When does API-only make sense?

• • Mobile app backend — your iOS/Android app needs an API, but the frontend is native code, not React
• • Microservice — one service in a larger architecture that handles a specific domain (payments, notifications, search)
• • Third-party integrations — building a public API that other developers consume (like Stripe or Twilio)
• • Separate frontend team — the frontend is built by a different team using their own stack (Vue, Svelte, Flutter)
• • Data pipeline — an API that ingests, transforms, and serves data with no user-facing UI

Scaffold the API

Let's build a task management API. One command gives you the full project:

grit new taskapi --api

The --api flag tells Grit to skip the frontend entirely. No apps/web, no apps/admin, no turbo.json, no pnpm-workspace.yaml. What you get is a clean Go API project:

taskapi/
├── docker-compose.yml          # PostgreSQL, Redis, MinIO, Mailhog
├── .env                        # Environment variables
├── .gitignore
├── README.md
└── apps/
    └── api/
        ├── cmd/
        │   └── server/
        │       └── main.go     # Entry point
        ├── internal/
        │   ├── config/         # Environment config
        │   ├── database/       # DB connection + migrations
        │   ├── handler/        # HTTP handlers
        │   ├── middleware/      # Auth, CORS, logging, cache
        │   ├── model/          # GORM models
        │   ├── router/         # Route definitions
        │   └── service/        # Business logic
        ├── go.mod
        └── go.sum

Compare this to a "triple" project (the default): no apps/web, no apps/admin, no packages/shared. The API stands alone.

Project Structure Tour

Let's walk through each folder in the API and understand what it does:

The pattern is simple: handlers receive HTTP requests, validate input, and call services. Services contain business logic, call the database through models, and return results. Handlers format the results as JSON responses. This separation keeps your code testable and organized.

HTTP Request
  → Router (matches URL to handler)
    → Middleware (auth, logging, CORS)
      → Handler (validates input, calls service)
        → Service (business logic, DB queries)
          → Model (GORM struct, database table)
        ← Service returns result
      ← Handler formats JSON response
    ← Middleware adds headers
  ← Router sends response
HTTP Response

Start the API

Starting an API-only project requires two steps: start the infrastructure services (database, Redis, etc.) and then start the Go API itself.

# Step 1: Start infrastructure (PostgreSQL, Redis, MinIO, Mailhog)
cd taskapi
docker compose up -d

# Step 2: Start the Go API
cd apps/api
go run cmd/server/main.go

You should see output like:

[GIN-debug] Listening and serving HTTP on :8080
Connected to PostgreSQL
Connected to Redis
GORM Studio available at /studio
API Docs available at /docs

Verify everything is working:

# Health check
curl localhost:8080/pulse/health

# Expected response:
# {"status":"ok","database":"connected","redis":"connected"}

Generate Resources

This is where the code generator shines. Instead of manually creating models, handlers, services, and routes for each entity, you describe the resource and Grit generates everything.

Let's generate two resources for our task API:

# Generate a Task resource
grit generate resource Task --fields "title:string,description:text,priority:int,done:bool,due_date:date:optional"

# Generate a Category resource
grit generate resource Category --fields "name:string:unique,color:string"

For each resource, Grit generates:

• • Model — internal/model/task.go with GORM struct and field tags
• • Service — internal/service/task_service.go with CRUD operations + pagination + filtering
• • Handler — internal/handler/task_handler.go with HTTP endpoints
• • Routes — injected into internal/router/router.go
• • Migration — auto-migrated by GORM on startup

The field type syntax is name:type with optional modifiers:

Test with API Docs

Grit's auto-generated API docs at /docs are not just documentation — they're an interactive testing tool. You can send real requests, see real responses, and explore every endpoint without writing a single curl command.

Let's create some test data through the API:

POST /api/categories
Content-Type: application/json

{
  "name": "Work",
  "color": "#6c5ce7"
}

POST /api/tasks
Content-Type: application/json

{
  "title": "Finish API course",
  "description": "Complete all 14 challenges in the Grit API Masterclass",
  "priority": 1,
  "done": false,
  "due_date": "2026-04-01"
}

Once you have data, test the list endpoint with pagination and filtering:

# Page 1, 5 items per page
GET /api/tasks?page=1&page_size=5

# Filter by priority
GET /api/tasks?priority=1

# Sort by due date (ascending)
GET /api/tasks?sort=due_date&order=asc

Add Relationships

Real APIs have relationships between resources. A Task belongs to a Category. An Order has many OrderItems. Grit handles relationships with the belongs_to field type.

To add a relationship, regenerate the Task resource with a category_id field:

grit generate resource Task --fields "title:string,description:text,priority:int,done:bool,due_date:date:optional,category_id:belongs_to:Category"

The category_id:belongs_to:Category field tells Grit:

• • Add a category_id column (foreign key) to the tasks table
• • Add a Category field to the Task struct for preloading
• • Include the Category data when fetching Tasks (GORM Preload)

Now when you create a task, you include the category_id:

POST /api/tasks
Content-Type: application/json

{
  "title": "Review pull request",
  "description": "Review the auth middleware changes",
  "priority": 2,
  "done": false,
  "category_id": 1
}

And when you fetch the task, the category data comes along:

{
  "data": {
    "id": 1,
    "title": "Review pull request",
    "description": "Review the auth middleware changes",
    "priority": 2,
    "done": false,
    "category_id": 1,
    "category": {
      "id": 1,
      "name": "Work",
      "color": "#6c5ce7"
    }
  }
}

Authentication

Every Grit API ships with JWT authentication. Users register, log in, receive a token, and send that token with every request to access protected endpoints.

The authentication flow:

curl -X POST localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@test.com","password":"password123"}'

# Response:
# {"data":{"id":1,"name":"John","email":"john@test.com","role":"USER"},"message":"Registration successful"}

curl -X POST localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john@test.com","password":"password123"}'

# Response:
# {"data":{"token":"eyJhbGciOiJIUzI1NiIs...","refresh_token":"...","user":{...}}}

curl localhost:8080/api/tasks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Without the token, protected endpoints return 401 Unauthorized

The Authorization header uses the Bearer scheme: the word "Bearer" followed by a space and then the token. This is the industry standard for JWT authentication.

Role-Based Access

Authentication answers "who are you?" Authorization answers "what can you do?"Grit supports role-based access control (RBAC) with two built-in roles: USER and ADMIN.

By default, all generated resource routes require authentication but allow any role. You can restrict routes to admin-only by adding the --roles flag:

# Generate a resource where write operations are admin-only
grit generate resource AuditLog --fields "action:string,user_id:int,details:text" --roles "ADMIN"

When a route is restricted to ADMIN, the middleware checks the user's role from the JWT token. If the user has the USER role, they get a 403 Forbidden response:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  }
}

You can promote a user to ADMIN through GORM Studio — just edit the user's record and change the role field from "USER" to "ADMIN".

Deploy the API

Grit includes a one-command deployment tool. It connects to your server via SSH, builds your Go binary, sets up a systemd service, configures Caddy for HTTPS, and starts everything.

grit deploy --host deploy@server.com --domain api.myapp.com

What grit deploy does behind the scenes:

• 1. Connects to your server via SSH
• 2. Uploads your project files
• 3. Builds the Go binary on the server (go build)
• 4. Creates a systemd service for auto-restart
• 5. Configures Caddy reverse proxy with automatic HTTPS
• 6. Starts PostgreSQL and Redis via Docker Compose
• 7. Runs database migrations
• 8. Starts the API

Your server needs: Ubuntu 22.04+, Docker, Go 1.21+, and Caddy. The deploy command handles the rest.

Summary

Here's everything you learned in this course:

• API-only mode (--api) gives you a lean Go API with no frontend overhead
• The project structure follows handler → service → model separation
• grit generate resource creates model, service, handler, and routes in one command
• Field types include string, text, int, bool, date, float, and belongs_to for relationships
• Every list endpoint gets automatic pagination, sorting, and filtering
• JWT authentication with register, login, and token-based access
• Role-based access control with USER and ADMIN roles
• API docs at /docs provide interactive testing without curl
• GORM Studio at /studio lets you browse and edit database records
• grit deploy ships your API to production in under 2 minutes