API & Library Design — Find the Bug¶

12 snippets where the bug lives in the caller, but the API made it inevitable. The signature, the default, the return type, or a "non-breaking" version bump steered an honest caller straight into the defect. Your job: find the caller's bug, then name the API change that makes that mistake impossible to write.

The discipline here is the provider's mirror image of debugging. A misuse-resistant API is one where the wrong call doesn't compile, doesn't construct, or doesn't type-check. Scott Meyers' rule — "make interfaces easy to use correctly and hard to use incorrectly" — is an operational test: if a competent caller reading only the signature can write a bug, the bug is the API's fault, not the caller's.

Table of Contents¶

• How to Use
• The Two Failure Modes
• Snippet 1 — Boolean trap, transposed (Java)
• Snippet 2 — Two same-typed params, swappable (Go)
• Snippet 3 — Returning a shared mutable internal (Java)
• Snippet 4 — size(): bytes or elements? (Python)
• Snippet 5 — Units not in the type: sleep(30) (Go)
• Snippet 6 — Nullable return the caller never checks (Java)
• Snippet 7 — A surprising default that bites (Python)
• Snippet 8 — getX that secretly mutates (Go)
• Snippet 9 — Overload resolution surprise (Java)
• Snippet 10 — The "non-breaking" default change, Hyrum's Law (Python)
• Snippet 11 — Param added with a bad default, silent behavior shift (Go)
• Snippet 12 — Return type widened across a "minor" bump (Java)
• Scorecard
• Related Topics

How to Use¶

Each snippet shows an API definition and a plausible caller. The caller looks reasonable — that is the point. Read the signature first, the way a real consumer would, then read the call. Form a hypothesis before expanding the answer.

For every snippet, answer three questions:

1. What does the caller actually do (vs. what they intended)?
2. Which design decision in the API invited that mistake? Name the specific feature: the boolean, the default, the return type, the version change.
3. What redesign makes the bug uncompilable or unconstructible? "Document it harder" is not an answer. Push the error to construction time, to the type system, or to a named alternative.

Difficulty tags: 🟢 warm-up · 🟡 realistic · 🔴 the kind that ships and survives three code reviews.

The Two Failure Modes¶

The left branch is a point-in-time defect: the signature was wrong the day it shipped. The right branch is an evolution defect: the signature was fine, then changed under a caller who upgraded a "safe" version. Both are the API author's responsibility.

Snippet 1 — Boolean trap, transposed (Java)¶

🟢 The classic. Read the call, then the signature.

// ---- Library ----
public final class Window {
    /**
     * @param visible    whether the window is shown
     * @param animate    animate the transition
     */
    public void setVisible(boolean visible, boolean animate) {
        this.visible = visible;
        if (animate) playTransition();
    }
}

// ---- Caller, in a different team's UI code ----
void onLogout() {
    mainWindow.setVisible(false, true);
}

What's the bug, and what API change prevents it?

public enum Visibility { SHOWN, HIDDEN }
public enum Transition { ANIMATED, IMMEDIATE }

public void setVisible(Visibility visibility, Transition transition) { ... }

// Caller — meaning is now in the call:
mainWindow.setVisible(Visibility.HIDDEN, Transition.IMMEDIATE);

Snippet 2 — Two same-typed params, swappable (Go)¶

🟡 The signature looks self-explanatory. It isn't.

// ---- Library ----
// Copy duplicates the contents of one file into another.
func Copy(dst, src string) error {
    data, err := os.ReadFile(src)
    if err != nil {
        return err
    }
    return os.WriteFile(dst, data, 0o644)
}

// ---- Caller ----
func backupConfig() error {
    // "copy the config to the backup location"
    return Copy("config.yaml", "config.yaml.bak")
}

What's the bug, and what API change prevents it?

type Source string
type Destination string

func Copy(src Source, dst Destination) error { ... }

// The call now states which is which, in the caller's order, and a swap won't compile:
err := Copy(Source("config.yaml"), Destination("config.yaml.bak"))

type CopyOpts struct {
    From string
    To   string
}
func Copy(o CopyOpts) error { ... }

err := Copy(CopyOpts{From: "config.yaml", To: "config.yaml.bak"})

Snippet 3 — Returning a shared mutable internal (Java)¶

🔴 The getter looks innocent. The caller "just reads" it.

// ---- Library ----
public final class Schedule {
    private final List<Slot> slots = new ArrayList<>();

    public List<Slot> getSlots() {
        return slots; // returns the live internal list
    }

    public boolean isFullyBooked() {
        return slots.size() >= capacity;
    }
}

// ---- Caller ----
void previewWithExtraSlot(Schedule schedule, Slot proposed) {
    List<Slot> preview = schedule.getSlots();
    preview.add(proposed);           // just to render a "what-if" view
    render(preview);
}

What's the bug, and what API change prevents it?

// Option A: unmodifiable view — caller's add() throws at runtime, loudly.
public List<Slot> getSlots() {
    return Collections.unmodifiableList(slots);
}

// Option B: defensive copy — caller can freely mutate their own list.
public List<Slot> getSlots() {
    return new ArrayList<>(slots);
}

// Best: don't expose the collection at all; expose the operations.
public boolean wouldBeFullyBookedWith(Slot proposed) {
    return slots.size() + 1 >= capacity;
}

Snippet 4 — size(): bytes or elements? (Python)¶

🟡 Two libraries, one method name, two meanings.

# ---- Library: a memory-mapped buffer ----
class Buffer:
    def __init__(self, data: bytes):
        self._data = data

    def size(self) -> int:
        """Number of BYTES held."""
        return len(self._data)

# ---- Library: a record set (built later, by the same team) ----
class RecordSet:
    def size(self) -> int:
        """Number of RECORDS held."""
        return len(self._records)

# ---- Caller: a progress bar that works on "anything with size()" ----
def stream_with_progress(source, sink, chunk_bytes: int = 4096):
    total = source.size()
    written = 0
    while True:
        chunk = source.read(chunk_bytes)
        if not chunk:
            break
        sink.write(chunk)
        written += len(chunk)            # bytes written
        report_progress(written / total) # fraction complete

What's the bug, and what API change prevents it?

class Buffer:
    def byte_count(self) -> int:
        return len(self._data)

class RecordSet:
    def record_count(self) -> int:
        return len(self._records)

from typing import Protocol

class HasByteCount(Protocol):
    def byte_count(self) -> int: ...

def stream_with_progress(source: HasByteCount, sink, chunk_bytes: int = 4096) -> None: ...

Snippet 5 — Units not in the type: sleep(30) (Go)¶

🟢 Looks like a sensible retry. The number lies.

// ---- Library ----
// Retry runs fn, and on failure waits `backoff` before trying again.
// backoff is in MILLISECONDS.
func Retry(attempts int, backoff int, fn func() error) error {
    var err error
    for i := 0; i < attempts; i++ {
        if err = fn(); err == nil {
            return nil
        }
        time.Sleep(time.Duration(backoff) * time.Millisecond)
    }
    return err
}

// ---- Caller ----
func fetchWithRetry() error {
    // "retry 3 times, waiting 30 seconds between attempts"
    return Retry(3, 30, callFlakyService)
}

What's the bug, and what API change prevents it?

func Retry(attempts int, backoff time.Duration, fn func() error) error {
    var err error
    for i := 0; i < attempts; i++ {
        if err = fn(); err == nil {
            return nil
        }
        time.Sleep(backoff)
    }
    return err
}

// Caller cannot write a unitless number; the unit is in the literal:
return Retry(3, 30*time.Second, callFlakyService)

Snippet 6 — Nullable return the caller never checks (Java)¶

🟡 The caller didn't forget to check. The signature hid that there was something to check.

// ---- Library ----
public final class UserRepository {
    /** Returns the user, or null if no user has that id. */
    public User findById(String id) {
        return cache.get(id); // null when absent
    }
}

// ---- Caller ----
String greet(String userId) {
    User user = repository.findById(userId);
    return "Welcome back, " + user.getDisplayName();
}

What's the bug, and what API change prevents it?

public Optional<User> findById(String id) {
    return Optional.ofNullable(cache.get(id));
}

// The caller can no longer dereference without acknowledging absence:
String greet(String userId) {
    return repository.findById(userId)
        .map(User::getDisplayName)
        .map(name -> "Welcome back, " + name)
        .orElse("Welcome, guest");
}

Snippet 7 — A surprising default that bites (Python)¶

🔴 The caller relied on a default that does the opposite of the safe thing.

# ---- Library: an HTTP client wrapper ----
import requests

class ApiClient:
    def __init__(self, base_url: str):
        self.base_url = base_url

    def get(self, path: str, *, verify_tls: bool = False):
        """Fetch a resource. verify_tls toggles certificate verification."""
        return requests.get(self.base_url + path, verify=verify_tls)

# ---- Caller ----
client = ApiClient("https://payments.internal.example.com")

def fetch_balance(account_id: str):
    resp = client.get(f"/accounts/{account_id}/balance")
    return resp.json()["balance"]

What's the bug, and what API change prevents it?

class ApiClient:
    def get(self, path: str, *, verify_tls: bool = True):  # secure by default
        return requests.get(self.base_url + path, verify=verify_tls)

class ApiClient:
    def __init__(self, base_url: str, *, allow_insecure_tls: bool = False):
        if allow_insecure_tls and not base_url.startswith("https://localhost"):
            raise ValueError("insecure TLS is only permitted against localhost")
        self._verify = not allow_insecure_tls

    def get(self, path: str):
        return requests.get(self.base_url + path, verify=self._verify)

Snippet 8 — getX that secretly mutates (Go)¶

🟡 A getter with a side effect. The caller called it "just to look."

// ---- Library ----
type Counter struct {
    next int
}

// GetID returns the next available ID.
func (c *Counter) GetID() int {
    id := c.next
    c.next++ // increments on every call
    return id
}

// ---- Caller ----
func logRequest(c *Counter, req Request) {
    log.Printf("handling request, current id=%d", c.GetID())
    process(req, c.GetID()) // "use the same id we just logged"
}

What's the bug, and what API change prevents it?

// Next consumes and returns the next ID. The verb signals state change.
func (c *Counter) Next() int {
    id := c.next
    c.next++
    return id
}

// ---- Caller, now obviously correct ----
func logRequest(c *Counter, req Request) {
    id := c.Next()                 // consumed once
    log.Printf("handling request, id=%d", id)
    process(req, id)               // reuse the captured value
}

Snippet 9 — Overload resolution surprise (Java)¶

🔴 The caller wrote a "remove this item" call. Java picked the other overload.

// ---- Library: java.util.List has both ----
//   E   remove(int index)        // removes the element at index
//   boolean remove(Object o)     // removes the first element equal to o

// ---- Caller ----
List<Integer> ids = new ArrayList<>(List.of(10, 20, 30, 40));

void dropId(int idToRemove) {
    ids.remove(idToRemove); // "remove the id 20 from the list"
}

// usage:
dropId(20);

What's the bug, and what API change prevents it?

ids.remove(Integer.valueOf(idToRemove)); // unambiguously remove(Object)

interface IdList {
    void removeAt(int index);    // positional
    void removeValue(int id);    // by value
}

Snippet 10 — The "non-breaking" default change, Hyrum's Law (Python)¶

🔴 The signature didn't change. The behavior did. The caller never touched their code.

# ---- Library v1.4 ----
def serialize(obj: dict) -> str:
    """Serialize a dict to a JSON string."""
    return json.dumps(obj)          # keys in insertion order

# ---- Library v1.5 (released as a "minor, non-breaking" bump) ----
def serialize(obj: dict) -> str:
    """Serialize a dict to a JSON string."""
    return json.dumps(obj, sort_keys=True)   # now sorted, "for nicer diffs"

# ---- Caller (unchanged across the upgrade) ----
def signed_payload(data: dict, secret: str) -> tuple[str, str]:
    body = serialize(data)
    signature = hmac_sha256(secret, body)   # sign the exact bytes
    return body, signature

What's the bug, and what API change prevents it?

def serialize(obj: dict, *, sort_keys: bool = False) -> str:
    """Serialize a dict to JSON. Key order is part of the contract;
    it does not change without a major version bump."""
    return json.dumps(obj, sort_keys=sort_keys)

Snippet 11 — Param added with a bad default, silent behavior shift (Go)¶

🔴 A new feature added a parameter. Existing callers got the new behavior for free — and didn't want it.

// ---- Library v2.0 ----
type ListOptions struct {
    Limit  int
    Offset int
}

func ListUsers(opts ListOptions) ([]User, error) { ... }

// ---- Library v2.1: added "soft-deleted" support ----
type ListOptions struct {
    Limit          int
    Offset         int
    IncludeDeleted bool // NEW: defaults to false... but the QUERY changed
}

func ListUsers(opts ListOptions) ([]User, error) {
    q := "SELECT * FROM users"
    if !opts.IncludeDeleted {
        // v2.1 also started actually writing deleted_at on delete;
        // before v2.1 rows were hard-deleted, so this filter is new.
        q += " WHERE deleted_at IS NULL"
    }
    // ...
}

// ---- Caller (a one-off admin export, unchanged) ----
func exportAllUsers() ([]User, error) {
    return ListUsers(ListOptions{Limit: 100000})
}

What's the bug, and what API change prevents it?

type DeletedFilter int
const (
    DeletedFilterUnset    DeletedFilter = iota // == old behavior
    ExcludeDeleted
    IncludeDeleted
)

type ListOptions struct {
    Limit   int
    Offset  int
    Deleted DeletedFilter // zero value == Unset == v2.0 semantics
}

func ListUsers(opts ListOptions) ([]User, error) {
    switch opts.Deleted {
    case ExcludeDeleted:
        // explicit filter
    default:
        // Unset preserves v2.0 behavior (which returned everything that existed)
    }
}

Snippet 12 — Return type widened across a "minor" bump (Java)¶

🟡 The return type became "more general." The caller's loop broke.

// ---- Library v3.2 ----
public List<Order> recentOrders() {
    return new ArrayList<>(store.findRecent());
}

// ---- Library v3.3 ("minor": widened return type to be more flexible") ----
public Collection<Order> recentOrders() {   // List -> Collection
    return store.findRecent();              // now may return a Set
}

// ---- Caller (compiled against v3.2, source unchanged) ----
void showFirstThree() {
    List<Order> orders = service.recentOrders();   // was fine in v3.2
    for (int i = 0; i < 3 && i < orders.size(); i++) {
        display(orders.get(i));                     // indexed access
    }
}

What's the bug, and what API change prevents it?

/** Orders, most-recent first. Ordering is guaranteed. */
public List<Order> recentOrders() {
    return List.copyOf(store.findRecent()); // immutable, ordered, indexable
}

Scorecard¶

Track which traps you spotted unaided. The right-hand column is the design principle each one teaches — that is what you carry into your own APIs.

Scoring:

• 10–12 unaided — you read signatures the way a misuse-resistant designer does. You'll catch these in review before they ship.
• 6–9 — solid instincts on point-in-time traps; revisit the evolution snippets (10–12), where the bug hides in a changelog, not a line of code.
• 0–5 — re-read each answer's "Why the API invited it." The recurring move is: the caller's mistake was the only natural reading of the signature. That reframing is the whole skill.

Related Topics¶

• junior.md — the foundational rules: minimal surface, intention-revealing signatures, sensible defaults.
• tasks.md — exercises: redesign a misuse-prone API into one that is hard to call wrong.
• Chapter README — the positive principles behind every fix above.
• Anti-Patterns — the broader catalog of designs that invite misuse.
• Refactoring — the mechanics of evolving a signature without breaking callers (deprecation, parallel change, expand-and-contract).