Tutorial overview

On this page

What you will build
What you need
The chapters
How code is shown

This tutorial builds one App from an empty directory to a binary running in production: a JSON API for a blog's posts. Each chapter adds to the code of the one before, and every command and output it shows comes from building that App. You will learn how to:

Create an App from the skeleton starter kit and run it while you work
Add routes whose handlers return values, and answer with errors clients can act on
Read and validate JSON request bodies
Share a service through the container with a service provider
Add a Command that people and agents run
Test the routes and the Command
Build the App into one binary and run it in production

What you will build

The App is called blog. By the last chapter it answers three routes, runs one Command of its own, and has tests for all of them:

Request or Command	What it does
`GET /posts`	Lists every post
`GET /posts/{id}`	Shows one post, or answers `404 Not Found`
`POST /posts`	Creates a post from a JSON body, or answers `422` naming each invalid field
`act posts:list`	Lists the posts in the terminal, or as JSON for an agent

Tinka has no database package yet, so the App keeps its posts in memory, in a small Store type of its own. They last until the App stops. The store's methods take a context and return errors, the way a store backed by a database does, so a data layer can replace it later without changing the handlers or the Command that use it.

What you need

You need Go 1.27 or later, and the tinka and act commands, which the first chapter installs. Check your Go version with go version. The tutorial sends requests with curl and assumes you can read Go: structs, methods and error handling.

The chapters

Work through them in order, since each one starts from the code the previous one ended with:

Create the App: install the tools, create the App from the skeleton starter kit, and run it with act serve, which rebuilds it on every save.
Routes and handlers: keep the posts in a store, and add GET /posts and GET /posts/{id} with handlers that return values and a 404 for a missing post.
Request bodies: add POST /posts, which decodes and validates a JSON body and answers 201 Created.
Services and providers: move the store into the App's container with a service provider, so every part of the App shares one.
Commands: add posts:list, a Command that uses the store from the container, and run it as a person and as an agent.
Testing: test the routes with tinkatest and the Command with clitest, and run them with act test.
Deploy: build the App with act build, and run the binary with its production environment and health checks.

How code is shown

The first time a file appears, it's shown whole, with its path above it, so you can copy it as it is. When a later step changes a file, only the change is shown, with added and removed lines marked, and enough lines around them to find the place. Commands you run are in shell blocks, and what they print follows in a block titled Output.