api-and-interface-design

API and Interface Design

This skill covers in-process boundaries: interfaces between packages, modules, or teams inside a single codebase or binary. For the shape of a wire-level contract (REST/RPC request/response bodies, error envelopes, pagination, versioning of an HTTP or RPC API), use the api-design skill instead — the two are complementary: a service's HTTP handler is itself a consumer of the internal interfaces this skill is about.

Core rule: define the interface where it's consumed, not where it's implemented

The single most common Go interface mistake is declaring an interface next to its implementation ("I built a Store, so I export a Store interface next to it"). This forces every consumer to depend on the producer's package just to get the interface type, and it tempts the producer into a single fat interface covering everything the type does.

// BAD: interface lives in the producer package, sized to the whole type.
package store

type Store interface {
    GetReservation(ctx context.Context, id string) (*Reservation, error)
    SaveReservation(ctx context.Context, r *Reservation) error
    GetGuest(ctx context.Context, id string) (*Guest, error)
    SaveGuest(ctx context.Context, g *Guest) error
    // ... ten more methods, because that's everything *SQLStore does
}

// GOOD: consumer package declares only the interface it needs.
package billing

// ReservationGetter is the only dependency billing has on storage.
type ReservationGetter interface {
    GetReservation(ctx context.Context, id string) (*Reservation, error)
}

func NewInvoicer(store ReservationGetter) *Invoicer { ... }

The producer (store.SQLStore) never needs to declare an interface at all — it just needs to satisfy whatever its consumers declare, which Go's structural typing does implicitly. This is the direct analogue of Go's own guidance ("accept interfaces, return structs"): a constructor should return a concrete type so callers get full access to it, and take interfaces as parameters so the function only asks for what it uses.