API Patterns

Reason about API design from first principles. The goal is judgment for your situation, not a template to paste.

How to use this skill

These notes are split into focused files. Open only the one that maps to the question in front of you instead of reading everything at once. The table below is your index.

File index

Sibling skills

Pre-flight checklist

Run through these before committing to a design:

• [ ] Who calls this API, and from where? (asked, not assumed)
• [ ] *Paradigm chosen for this problem* (REST / GraphQL / tRPC)
• [ ] One response shape, applied everywhere
• [ ] A story for how the API changes over time
• [ ] Identity and access model decided
• [ ] Throttling thought through
• [ ] A plan for keeping docs alive

Traps to avoid

Stop doing this:

• Reaching for REST reflexively on every project
• Naming endpoints after actions (e.g. /fetchUsers)
• Letting each route return a differently shaped body
• Leaking stack traces or DB errors to callers
• Shipping with no throttling at all

Do this instead:

• Let the consumers and constraints pick the paradigm
• Pin down client needs by asking first
• Treat documentation as part of the deliverable
• Map outcomes to the right HTTP codes

Script