Overview

The API template creates a well-structured JSON API service. An API (Application Programming Interface) is a way for programs to talk to each other - when you build an API, you create endpoints (URLs) that other programs can call to get or send data, usually in JSON format. This template is designed for production use with a clean architecture that scales as your project grows.

When to Use This Template

Use the API template when:

Building a REST API - JSON endpoints for web or mobile clients
Multiple developers - Clear structure everyone can follow
Production service - Ready for deployment
Need organization - More than a few routes

What You Get

A complete project structure with:

Feature-based organization - Code grouped by domain
Configuration management - Environment-based config
App lifecycle - Clean startup and shutdown
Example endpoints - Health check, echo, users

Quick Start

# Create the project
mizu new myapi --template api

# Enter the project
cd myapi

# Install dependencies
go mod tidy

# Run the server
mizu dev

Test it:

curl http://localhost:8080/health
curl http://localhost:8080/hello
curl http://localhost:8080/api/users

Project Structure

myapi/
├── cmd/
│   └── api/
│       └── main.go         # Entry point
├── app/
│   └── api/
│       ├── app.go          # Application setup
│       ├── config.go       # Configuration
│       └── routes.go       # Route registration
├── feature/
│   ├── echo/
│   │   └── http.go         # Echo handler
│   ├── health/
│   │   └── http.go         # Health check
│   ├── hello/
│   │   └── http.go         # Hello handler
│   └── users/
│       └── http.go         # Users API
├── go.mod
└── .gitignore

Key Features

Feature-Based Organization

Each feature (domain/module) gets its own folder:

feature/
├── users/     # User management
├── products/  # Product catalog
├── orders/    # Order processing
└── auth/      # Authentication

This keeps related code together and makes it easy to find things.

Configuration Management

Configuration is loaded from environment variables:

type Config struct {
    Addr string // Server address
    Dev  bool   // Development mode
}

func LoadConfig() Config {
    return Config{
        Addr: getEnv("ADDR", ":8080"),
        Dev:  getEnv("DEV", "true") == "true",
    }
}

Application Structure

The App struct manages lifecycle:

type App struct {
    cfg Config
    app *mizu.App
}

func New(cfg Config) *App {
    a := &App{cfg: cfg}
    a.app = mizu.New()
    a.routes()
    return a
}

Example Routes

Health Check

curl http://localhost:8080/health

{"status":"ok"}

Hello Endpoint

curl http://localhost:8080/hello

Hello from myapi

Users API

curl http://localhost:8080/api/users

[{"id":"1","name":"Alice"},{"id":"2","name":"Bob"}]

Echo Endpoint

curl -X POST http://localhost:8080/echo -d '{"message":"hi"}' -H "Content-Type: application/json"

{"message":"hi"}

Why This Structure?

Scalability

As your API grows, add new features without cluttering existing code:

# Add a new feature
mkdir -p feature/products
touch feature/products/http.go

Testability

Each feature can be tested independently:

go test ./feature/users/...
go test ./feature/products/...

Team Collaboration

Clear boundaries mean less merge conflicts:

Developer A works on feature/users/
Developer B works on feature/products/

Maintainability

Find code easily:

“Where’s the user creation logic?” → feature/users/
“Where are routes defined?” → app/api/routes.go
“Where’s the config?” → app/api/config.go

Comparison with Minimal

Aspect	minimal	api
Files	1	10+
Structure	None	Feature-based
Config	Hardcoded	Environment variables
Suitable for	Learning, prototypes	Production
Scalability	Poor	Good

Getting Started

Commands

Templates Overview

Minimal Template

API Template

Contract Template

Web Template

Live Template

Sync Template

Reference

When to Use This Template

What You Get

Quick Start

Project Structure

Key Features

Feature-Based Organization

Configuration Management

Application Structure

Example Routes

Health Check

Hello Endpoint

Users API

Echo Endpoint

Why This Structure?

Scalability

Testability

Team Collaboration

Maintainability

Comparison with Minimal

Next Steps

Project Structure

Tutorial

​When to Use This Template

​What You Get

​Quick Start

​Project Structure

​Key Features

​Feature-Based Organization

​Configuration Management

​Application Structure

​Example Routes

​Health Check

​Hello Endpoint

​Users API

​Echo Endpoint

​Why This Structure?

​Scalability

​Testability

​Team Collaboration

​Maintainability

​Comparison with Minimal

​Next Steps

Project Structure

Tutorial

When to Use This Template

What You Get

Quick Start

Project Structure

Key Features

Feature-Based Organization

Configuration Management

Application Structure

Example Routes

Health Check

Hello Endpoint

Users API

Echo Endpoint

Why This Structure?

Scalability

Testability

Team Collaboration

Maintainability

Comparison with Minimal

Next Steps