File-backed notes API
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:
| Method | Path | Result |
|---|---|---|
POST | /notes | Create a note and return 201 Created |
GET | /notes | Return 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.
abc from the route. The service normalises and validates domain values, sets the update time, and asks the store to replace the note. The store returns note.ErrNotFound if abc is absent. The handler is the layer that maps that domain error to HTTP 404, because HTTP is a transport concern.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.