Quick Start

This guide walks you through creating a mobile backend with Mizu. You’ll have a working API with device detection, versioning, and mobile-optimized responses in under 5 minutes.

Prerequisites

Before starting, make sure you have:

Go 1.22 or later - Download Go
Mizu CLI - Install with go install github.com/go-mizu/mizu/cmd/cli@latest

Verify your installation:

go version    # Should show 1.22 or later
mizu version  # Should show the installed Mizu CLI version

Create Your First Mobile Backend

Step 1: Create a New Project

Create a minimal Mizu project:

mizu new ./my-mobile-api --template minimal
cd my-mobile-api

Step 2: Add Mobile Middleware

Update your main.go to add mobile support:

package main

import (
    "github.com/go-mizu/mizu"
    "github.com/go-mizu/mizu/mobile"
)

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

    // Add mobile device detection
    app.Use(mobile.New())

    // Add API versioning
    app.Use(mobile.VersionMiddleware(mobile.VersionOptions{
        Supported:  []mobile.Version{{2, 0}, {1, 0}},
        Deprecated: []mobile.Version{{1, 0}},
        Default:    mobile.Version{Major: 2},
    }))

    // API routes
    app.Get("/api/hello", handleHello)
    app.Get("/api/users", handleUsers)

    app.Listen(":3000")
}

func handleHello(c *mizu.Ctx) error {
    device := mobile.DeviceFromCtx(c)

    return c.JSON(200, map[string]any{
        "message":    "Hello from Mizu Mobile!",
        "platform":   device.Platform.String(),
        "app_version": device.AppVersion,
        "device_id":  device.DeviceID,
    })
}

func handleUsers(c *mizu.Ctx) error {
    version := mobile.VersionFromCtx(c)

    users := []map[string]any{
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"},
    }

    // Version-aware response
    if version.AtLeast(2, 0) {
        // v2: Include metadata
        return c.JSON(200, map[string]any{
            "data":  users,
            "count": len(users),
        })
    }

    // v1: Simple array
    return c.JSON(200, users)
}

Step 3: Run the Server

go run main.go

Your mobile backend is now running at http://localhost:3000.

Test Your API

Test with Mobile Headers

# Basic request with mobile headers
curl -H "X-Device-ID: device-123" \
     -H "X-App-Version: 2.1.0" \
     -H "X-Platform: ios" \
     http://localhost:3000/api/hello

Response:

{
  "message": "Hello from Mizu Mobile!",
  "platform": "ios",
  "app_version": "2.1.0",
  "device_id": "device-123"
}

Test API Versioning

# v2 API (default)
curl -H "X-API-Version: v2" \
     http://localhost:3000/api/users

# Response: {"data": [...], "count": 2}

# v1 API (deprecated)
curl -H "X-API-Version: v1" \
     http://localhost:3000/api/users

# Response: [...] (simple array)
# Response header: X-API-Deprecated: true

Add More Features

Require Device ID

app.Use(mobile.WithOptions(mobile.Options{
    RequireDeviceID: true,
}))

Now requests without X-Device-ID return 400 Bad Request.

Enforce Minimum App Version

app.Use(mobile.WithOptions(mobile.Options{
    RequireAppVersion: true,
    MinAppVersion:     "1.5.0",
}))

Requests with app versions below 1.5.0 return 426 Upgrade Required.

Add Offline Sync

app.Get("/api/sync", func(c *mizu.Ctx) error {
    req := mobile.ParseSyncRequest(c)

    var delta mobile.Delta[Item]
    if req.IsInitial() {
        // Full sync
        delta.Created = getAllItems()
    } else {
        // Delta sync
        since := req.Since()
        delta.Created = getCreatedSince(since)
        delta.Updated = getUpdatedSince(since)
        delta.Deleted = getDeletedSince(since)
    }

    token := mobile.NewSyncToken(time.Now())
    return c.JSON(200, mobile.NewSyncDelta(delta, token, false))
})

Add Push Token Registration

app.Post("/api/push/register", func(c *mizu.Ctx) error {
    token := mobile.ParsePushToken(c)
    if token == nil {
        return mobile.SendError(c, 400, mobile.NewError(
            mobile.ErrInvalidRequest,
            "Missing push token",
        ))
    }

    // Validate token format
    if !mobile.ValidateToken(token.Token, token.Provider) {
        return mobile.SendError(c, 400, mobile.NewError(
            mobile.ErrValidation,
            "Invalid push token format",
        ))
    }

    // Save token to database
    // db.SavePushToken(token)

    return c.NoContent()
})

Create a Mobile Client

Using a Template

Create a complete mobile client with matching SDK:

# iOS app
mizu new ./my-ios-app --template mobile/ios

# Android app
mizu new ./my-android-app --template mobile/android

# Flutter app
mizu new ./my-flutter-app --template mobile/flutter

# React Native app
mizu new ./my-rn-app --template mobile/reactnative

Manual Client Setup

iOS (Swift)

class APIClient {
    let baseURL = "http://localhost:3000"
    let deviceID = UIDevice.current.identifierForVendor?.uuidString ?? ""

    func request(_ endpoint: String) async throws -> Data {
        var request = URLRequest(url: URL(string: baseURL + endpoint)!)

        // Add mobile headers
        request.setValue(deviceID, forHTTPHeaderField: "X-Device-ID")
        request.setValue(Bundle.main.appVersion, forHTTPHeaderField: "X-App-Version")
        request.setValue("ios", forHTTPHeaderField: "X-Platform")
        request.setValue("v2", forHTTPHeaderField: "X-API-Version")

        let (data, _) = try await URLSession.shared.data(for: request)
        return data
    }
}

Android (Kotlin)

class ApiClient(private val baseUrl: String) {
    private val client = OkHttpClient()
    private val deviceId = Settings.Secure.getString(
        context.contentResolver,
        Settings.Secure.ANDROID_ID
    )

    fun createRequest(endpoint: String): Request {
        return Request.Builder()
            .url("$baseUrl$endpoint")
            .header("X-Device-ID", deviceId)
            .header("X-App-Version", BuildConfig.VERSION_NAME)
            .header("X-Platform", "android")
            .header("X-API-Version", "v2")
            .build()
    }
}

Flutter (Dart)

class ApiClient {
  final String baseUrl;
  final String deviceId;

  ApiClient({required this.baseUrl, required this.deviceId});

  Future<http.Response> get(String endpoint) {
    return http.get(
      Uri.parse('$baseUrl$endpoint'),
      headers: {
        'X-Device-ID': deviceId,
        'X-App-Version': packageInfo.version,
        'X-Platform': Platform.operatingSystem,
        'X-API-Version': 'v2',
      },
    );
  }
}

Project Structure

A typical mobile backend project:

my-mobile-api/
├── cmd/
│   └── server/
│       └── main.go          # Entry point
├── app/
│   └── server/
│       ├── app.go           # Mizu app setup
│       ├── config.go        # Configuration
│       ├── routes.go        # Route definitions
│       └── handlers/
│           ├── users.go     # User handlers
│           ├── sync.go      # Sync handlers
│           └── push.go      # Push handlers
├── internal/
│   ├── models/              # Data models
│   └── services/            # Business logic
├── go.mod
└── Makefile

Common Patterns

Platform-Specific Responses

func handler(c *mizu.Ctx) error {
    device := mobile.DeviceFromCtx(c)

    response := map[string]any{
        "message": "Hello",
    }

    // Platform-specific data
    switch device.Platform {
    case mobile.PlatformIOS:
        response["store_url"] = "https://apps.apple.com/app/id123"
    case mobile.PlatformAndroid:
        response["store_url"] = "https://play.google.com/store/apps/details?id=com.example"
    }

    return c.JSON(200, response)
}

Graceful Version Migration

func handler(c *mizu.Ctx) error {
    version := mobile.VersionFromCtx(c)

    switch {
    case version.AtLeast(3, 0):
        return handleV3(c)
    case version.AtLeast(2, 0):
        return handleV2(c)
    default:
        return handleV1(c)
    }
}

Structured Error Responses

func handler(c *mizu.Ctx) error {
    if !authorized {
        return mobile.SendError(c, 401, mobile.NewError(
            mobile.ErrUnauthorized,
            "Invalid credentials",
        ).WithDetails("reason", "token_expired"))
    }

    if !valid {
        return mobile.SendError(c, 400, mobile.NewError(
            mobile.ErrValidation,
            "Invalid request",
        ).WithDetails("field", "email").
          WithDetails("error", "invalid format"))
    }

    return c.JSON(200, data)
}

Next Steps

You’ve created your first mobile backend! Here’s what to explore next:

Device Detection

Deep dive into device parsing and validation

API Versioning

Learn about version management

Offline Sync

Implement delta synchronization

Push Notifications

Handle push token registration

Getting Started

Core Concepts

Backend Features

Native Platforms

Cross-Platform

Web & Games

Deployment

Templates

Reference

Prerequisites

Create Your First Mobile Backend

Step 1: Create a New Project

Step 2: Add Mobile Middleware

Step 3: Run the Server

Test Your API

Test with Mobile Headers

Test API Versioning

Add More Features

Require Device ID

Enforce Minimum App Version

Add Offline Sync

Add Push Token Registration

Create a Mobile Client

Using a Template

Manual Client Setup

iOS (Swift)

Android (Kotlin)

Flutter (Dart)

Project Structure

Common Patterns

Platform-Specific Responses

Graceful Version Migration

Structured Error Responses

Next Steps

Device Detection

API Versioning

Offline Sync

Push Notifications

​Prerequisites

​Create Your First Mobile Backend

​Step 1: Create a New Project

​Step 2: Add Mobile Middleware

​Step 3: Run the Server

​Test Your API

​Test with Mobile Headers

​Test API Versioning

​Add More Features

​Require Device ID

​Enforce Minimum App Version

​Add Offline Sync

​Add Push Token Registration

​Create a Mobile Client

​Using a Template

​Manual Client Setup

​iOS (Swift)

​Android (Kotlin)

​Flutter (Dart)

​Project Structure

​Common Patterns

​Platform-Specific Responses

​Graceful Version Migration

​Structured Error Responses

​Next Steps

Device Detection

API Versioning

Offline Sync

Push Notifications

Prerequisites

Create Your First Mobile Backend

Step 1: Create a New Project

Step 2: Add Mobile Middleware

Step 3: Run the Server

Test Your API

Test with Mobile Headers

Test API Versioning

Add More Features

Require Device ID

Enforce Minimum App Version

Add Offline Sync

Add Push Token Registration

Create a Mobile Client

Using a Template

Manual Client Setup

iOS (Swift)

Android (Kotlin)

Flutter (Dart)

Project Structure

Common Patterns

Platform-Specific Responses

Graceful Version Migration

Structured Error Responses

Next Steps