Go API

A Go API built with net/http reports its runtime, answers health checks, and lets you list or add todos. Tokay compiles the source and runs the binary as one Web Service.

Last updated

AI agent? Start with llms.txt.

The project is intentionally close to what you would write for any Go host. You keep the standard library server and Tokay handles the build and live routing.

Runtime
Go
Framework
net/http
Service types
Web Service
Resources
None
Required secrets
None

What it does

The root route tells you which Go runtime compiled the service.

Fetch /todos to see three starting tasks. Post a JSON title and the API adds it with the next ID. Malformed JSON, unknown fields, and blank titles receive a helpful 400 response.

Use /health when you need a simple check that the process is answering requests.

Deploy it

Bring this folder to Tokay any way you like. Hand it to your AI assistant, drag the unzipped folder in under Add code, or push it with Git. Tokay figures out the rest.

Haven't connected your assistant yet? Set it up once, then ask it to deploy this example. Agents can use Tokay MCP at https://mcp.tokay.io/mcp or the Tokay API, and our agent instructions cover both.

New to Tokay? The getting started guide walks you through your first deploy.

Try it

Point the commands at your live URL and prove that a write appears in the next read.

export APP_URL="https://your-app.tokay.app"
curl -X POST "$APP_URL/todos" \
  -H 'Content-Type: application/json' \
  -d '{"title":"ship the next thing"}'
curl "$APP_URL/todos"

The list includes the new title while this process is running. A fresh deployment resets it to the sample data because storage is deliberately outside this starter.

How it works

You do not need to ship a compiled artifact. Tokay detects the Go module from go.mod, builds main.go, supplies the port, and starts the program.

Secrets

There are no secrets to configure. The API has no outside dependencies.

Grow from here

Browse the Tokay examples catalog when you want saved data or background work.

go.mod Raw

module example.com/tokay/go-api

go 1.26

main.go Raw

package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"
	"runtime"
	"strings"
	"sync"
)

type todo struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
}

var (
	todos = []todo{
		{ID: 1, Title: "deploy this ✓"},
		{ID: 2, Title: "add a database"},
		{ID: 3, Title: "tell a friend"},
	}
	todosMu sync.Mutex
)

func writeJSON(response http.ResponseWriter, status int, value any) {
	response.Header().Set("Content-Type", "application/json")
	response.WriteHeader(status)
	if err := json.NewEncoder(response).Encode(value); err != nil {
		log.Printf("write response: %v", err)
	}
}

func hello(response http.ResponseWriter, _ *http.Request) {
	writeJSON(response, http.StatusOK, map[string]string{
		"message": "Hello from net/http",
		"runtime": runtime.Version(),
	})
}

func health(response http.ResponseWriter, _ *http.Request) {
	writeJSON(response, http.StatusOK, map[string]bool{"ok": true})
}

func listTodos(response http.ResponseWriter, _ *http.Request) {
	todosMu.Lock()
	defer todosMu.Unlock()
	writeJSON(response, http.StatusOK, todos)
}

func createTodo(response http.ResponseWriter, request *http.Request) {
	var input struct {
		Title string `json:"title"`
	}
	decoder := json.NewDecoder(http.MaxBytesReader(response, request.Body, 1<<20))
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(&input); err != nil {
		writeJSON(response, http.StatusBadRequest, map[string]string{"error": "send a JSON title"})
		return
	}

	input.Title = strings.TrimSpace(input.Title)
	if input.Title == "" {
		writeJSON(response, http.StatusBadRequest, map[string]string{"error": "title is required"})
		return
	}

	todosMu.Lock()
	created := todo{ID: len(todos) + 1, Title: input.Title}
	todos = append(todos, created)
	todosMu.Unlock()
	writeJSON(response, http.StatusCreated, created)
}

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "3000"
	}

	mux := http.NewServeMux()
	mux.HandleFunc("GET /", hello)
	mux.HandleFunc("GET /health", health)
	mux.HandleFunc("GET /todos", listTodos)
	mux.HandleFunc("POST /todos", createTodo)

	server := &http.Server{Addr: "0.0.0.0:" + port, Handler: mux}
	log.Printf("Go API listening on port %s", port)
	log.Fatal(server.ListenAndServe())
}

Built from revision 259b82f

Guide: Deploy a Go app