Designing the Service

// Command design prints the API contract for the notes service. It is the
// design written as code: the resource, the storage contract, the routes.
package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

// Note is the one resource this service exposes.
type Note struct {
	ID      string    `json:"id"`
	Text    string    `json:"text"`
	Created time.Time `json:"created_at"`
}

// ErrNotFound is what the store returns when no row has that id.
var ErrNotFound = errors.New("note not found")

// Store is everything the service needs from Postgres, and nothing more.
// Deciding it before writing any SQL keeps the rules free of database detail.
type Store interface {
	Create(ctx context.Context, text string) (Note, error)
	Get(ctx context.Context, id string) (Note, error)
	List(ctx context.Context, limit int) ([]Note, error)
	Delete(ctx context.Context, id string) error
}

// route is one line of the contract. Two field names on one line is
// shorthand for two lines of the same type: "pattern string" followed by
// "failure string". The two forms declare exactly the same fields.
type route struct {
	pattern, failure string
	success          int
}

func main() {
	routes := []route{
		{pattern: "POST /notes", failure: "400 invalid body", success: 201},
		{pattern: "GET /notes", failure: "400 bad limit", success: 200},
		{pattern: "GET /notes/{id}", failure: "404 unknown id", success: 200},
		{pattern: "DELETE /notes/{id}", failure: "404 unknown id", success: 204},
		{pattern: "GET /healthz", failure: "none", success: 200},
		{pattern: "GET /readyz", failure: "503 store unreachable", success: 200},
	}
	for _, r := range routes {
		fmt.Printf("%-20s -> %d  (%s)\n", r.pattern, r.success, r.failure)
	}
}

// Output:
// POST /notes          -> 201  (400 invalid body)
// GET /notes           -> 200  (400 bad limit)
// GET /notes/{id}      -> 200  (404 unknown id)
// DELETE /notes/{id}   -> 204  (404 unknown id)
// GET /healthz         -> 200  (none)
// GET /readyz          -> 200  (503 store unreachable)