Skip to main content
This guide gets you from zero to running app as fast as possible. You’ll create a simple JSON API with one route.

​
Prerequisites

  • Go 1.22 or later installed (download)
  • A terminal and text editor
Verify Go is installed: 
go version
# go version go1.22.0 darwin/arm64

​
Step 1: Create a project

mkdir myapp && cd myapp
go mod init myapp

​
Step 2: Install Mizu

go get github.com/go-mizu/mizu

​
Step 3: Create main.go

Create a file named main.go: 
package main

import "github.com/go-mizu/mizu"

func main() {
    app := mizu.New()

    app.Get("/", func(c *mizu.Ctx) error {
        return c.JSON(200, map[string]string{
            "message": "Hello, Mizu!",
        })
    })

    app.Listen(":3000")
}

​
Step 4: Run it

go run main.go
You’ll see: 
INFO server starting addr=:3000

​
Step 5: Test it

Open a new terminal and run: 
curl http://localhost:3000
You’ll get: 
{"message":"Hello, Mizu!"}
Press Ctrl+C in the first terminal to stop the server.

​
What just happened?

  1. mizu.New() created an app with a router and default middleware
  2. app.Get("/", ...) registered a handler for GET requests to ”/”
  3. c.JSON(200, ...) sent a JSON response with status 200
  4. app.Listen(":3000") started the HTTP server

​
Add more routes

Expand your main.go: 
package main

import "github.com/go-mizu/mizu"

func main() {
    app := mizu.New()

    // Homepage
    app.Get("/", func(c *mizu.Ctx) error {
        return c.JSON(200, map[string]string{
            "message": "Hello, Mizu!",
        })
    })

    // Get user by ID
    app.Get("/users/{id}", func(c *mizu.Ctx) error {
        id := c.Param("id")
        return c.JSON(200, map[string]string{
            "id":   id,
            "name": "User " + id,
        })
    })

    // Create a user
    app.Post("/users", func(c *mizu.Ctx) error {
        var input struct {
            Name string `json:"name"`
        }
        if err := c.BindJSON(&input, 1<<20); err != nil {
            return c.JSON(400, map[string]string{"error": err.Error()})
        }
        return c.JSON(201, map[string]string{
            "id":   "123",
            "name": input.Name,
        })
    })

    app.Listen(":3000")
}
Test the new routes: 
# Get a user
curl http://localhost:3000/users/42

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

​
Project structure

For larger apps, organize code into packages: 
myapp/
├── main.go           # Entry point
├── go.mod
├── go.sum
├── handlers/         # HTTP handlers
│   └── users.go
├── services/         # Business logic
│   └── user.go
└── models/           # Data types
    └── user.go

​
What’s next?

Core Concepts

Learn how Mizu components work together.

Build an API

Create a complete REST API tutorial.

Project Structure

Best practices for organizing your code.

Deployment

Deploy your app to production.