API Design Assistant

An API is a promise to strangers. Every decision you make now constrains every user forever — or forces a breaking change. Design for the caller you'll never talk to.

The three questions

For every public surface, ask:

1. Can a stranger call this correctly on the first try? (Usability)
2. Can you add to it without breaking existing callers? (Evolvability)
3. Does it do what the name says — and nothing else? (Surprise)

Usability smells

Evolvability — can you change it later?

Adding is cheap. Removing is forever. Every parameter, every field, every endpoint: could you live with it for 5 years?

Surprise — the hidden contract

The name IS the documentation most callers read. If behavior doesn't match the name:

• getUser(id) that creates a user if missing → surprise. Call it getOrCreateUser.
• list() that returns the first 100 → surprise. Call it listPage or document loudly.
• setX(v) that also triggers a network call → surprise. Setters should be cheap.
• close() that can't be called twice → surprise. Idempotent close is the convention.

Worked example — function review

Proposed:

def send_email(to, subject, body, html, cc, bcc, attachments, retry, async_):
    ...

Review:

Suggested:

def send_email(
    to: str | list[str],
    subject: str,
    body: str,
    *,
    body_format: Literal["text", "html"] = "text",
    cc: list[str] = (),
    bcc: list[str] = (),
    attachments: list[Attachment] = (),
    retry: int = 0,
) -> EmailResult:

Keyword-only after *. async_ dropped — make it a separate send_email_async(). Return a result object so you can add message_id, delivered_at, etc. later.

REST-specific checklist

• Nouns in paths, verbs in methods: GET /users/42, not GET /getUser?id=42.
• Status codes carry meaning: 404 for not-found, 400 for bad input, 422 for valid-but-rejected. Don't 200 {"error": "..."}.
• Pagination from day one. ?limit=&cursor= — you'll need it once the table grows.
• Error body has a stable shape. {"error": {"code": "...", "message": "..."}} — clients pattern-match on it.
• PATCH for partial update, PUT for full replace — don't make PUT mean PATCH.

Do not

• Do not add a parameter "just in case." Every parameter is a promise to keep working.
• Do not overload one endpoint/function to do five things controlled by a flag. Five things = five names.
• Do not return different shapes from one endpoint based on a query param. One endpoint, one shape.
• Do not break a public API in a minor version. If the change is breaking, the version bump is major — that's what major means.
• Do not ship an undocumented API and call it "internal." If it's reachable, someone will use it, and now it's public whether you meant it or not.

Output format

## Usability
| Issue | Severity | Fix |
| ... | ... | ... |

## Evolvability
<what happens when you need to add X — can you, without breaking callers?>

## Surprise
<does behavior match the name? list mismatches>

## Suggested signature / contract
<concrete revision>