File-backed notes API

Design an intermediate HTTP API with clear layers, durable JSON storage, and predictable errors.

File-backed notes API

This project combines the language, standard-library, and API lessons into one service. It deliberately stores data in a JSON file instead of a database. That keeps the persistence rules visible while you practise boundaries that will still matter when a database is introduced.

What you will learn

  • turn product requirements into a small domain model;
  • separate HTTP, business, and storage responsibilities;
  • define errors that do not leak implementation details;
  • plan safe file updates and concurrent access;
  • identify when a file store is no longer appropriate.

Requirements

The API must support:

MethodPathResult
POST/notesCreate a note and return 201 Created
GET/notesReturn all notes
GET/notes/{id}Return one note or 404 Not Found
PUT/notes/{id}Replace a note or return 404 Not Found
DELETE/notes/{id}Delete a note and return 204 No Content

Reject malformed JSON and blank titles with 400 Bad Request. Limit request bodies so one client cannot make the process consume unbounded memory.

Start with the domain

package note

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

var ErrNotFound = errors.New("note not found")

type Note struct {
    ID        string    `json:"id"`
    Title     string    `json:"title"`
    Body      string    `json:"body"`
    CreatedAt time.Time `json:"createdAt"`
    UpdatedAt time.Time `json:"updatedAt"`
}

type Store interface {
    List(context.Context) ([]Note, error)
    Get(context.Context, string) (Note, error)
    Create(context.Context, Note) error
    Replace(context.Context, Note) error
    Delete(context.Context, string) error
}

The domain owns the meaning of a note and ErrNotFound. It does not know about JSON files, URLs, or HTTP status codes. context.Context is the first parameter because callers control cancellation; do not store a context inside a long-lived struct.

Choose simple boundaries

HTTP request
    -> handler: decode, validate, map HTTP details
        -> service: apply note rules and timestamps
            -> store: read or persist notes
HTTP response

For a project this size, internal/note and internal/httpapi are enough. Add a layer only when it owns a real responsibility. A large directory tree does not make a design clean.

Error contract

Handlers may map errors as follows:

  • invalid client input → 400;
  • note.ErrNotFound → 404;
  • unsupported method → 405;
  • unexpected internal failure → 500, with details logged on the server rather than returned to the client.

Use errors.Is when checking wrapped sentinel errors.

Practice

Sketch the request path for PUT /notes/abc. Name the responsibility of the handler, service, and store, and state which layer decides that a missing note becomes HTTP 404.

Summary

  • Begin with observable behaviour and a small domain model.
  • Keep transport, business rules, and persistence separate.
  • Domain errors cross boundaries; HTTP status codes stay in handlers.
  • File storage is useful for learning, but it needs explicit durability and concurrency rules.

Ready to wrap up?

Mark this complete when you can explain the main idea and finish the practice task.

Copyright © 2026