Interface And API Rules
Definition
Define the contracts modules use to communicate. An interface is everything callers must know: signatures, data shapes, behavior, ordering, errors, side effects, performance expectations, and informal rules.
Process
- Identify the caller's goal and design the smallest interface that satisfies common cases.
- Keep rare features optional and out of the common path.
- Hide implementation details, persistence shapes, transport types, and vendor SDKs.
- Document informal behavior that code signatures cannot express.
- Review whether the interface is simpler than the implementation it hides.
- Remove pass-through variables and methods unless they create a distinct abstraction.
Rules
- Design APIs around intent, not internal steps.
- Do not expose fields just because the implementation has them.
- Prefer fewer, more powerful operations over many shallow methods.
- Make defaults live behind the interface when callers should not care.
- Treat exceptions and errors as part of the interface.
Examples
- Good:
reserveSlot(patientId, requestedWindow) hides lock, conflict, and timezone details.
- Bad:
checkSlot, lockSlot, createVisit, sendCalendarInvite required in exact caller order.
- Good API comment: describes what happens if no slot is available.
- Bad API comment: explains the table queries used internally.
Vocabulary
- Formal interface: signature, public fields, schema, route, or type.
- Informal interface: behavior, constraints, side effects, timing, and errors.
- Abstraction: a simplified view that omits unneeded detail.
- Pass-through method: a method that mostly forwards to another method.
- Common path: the normal use case the interface should make simple.
Expected Outcome
Produce API rules covering allowed exports, input and output shapes, error contracts, documentation requirements, forbidden leaks, and review questions for interface depth.
1---2name: interface-and-api-rules3description: Define or audit how modules, layers, services, and external clients communicate. Use when designing APIs, reviewing public interfaces, preventing implementation leakage, or simplifying contracts between modules.4---56# Interface And API Rules78## Definition910Define the contracts modules use to communicate. An interface is everything callers must know: signatures, data shapes, behavior, ordering, errors, side effects, performance expectations, and informal rules.1112## Process13141. Identify the caller's goal and design the smallest interface that satisfies common cases.152. Keep rare features optional and out of the common path.163. Hide implementation details, persistence shapes, transport types, and vendor SDKs.174. Document informal behavior that code signatures cannot express.185. Review whether the interface is simpler than the implementation it hides.196. Remove pass-through variables and methods unless they create a distinct abstraction.2021## Rules2223- Design APIs around intent, not internal steps.24- Do not expose fields just because the implementation has them.25- Prefer fewer, more powerful operations over many shallow methods.26- Make defaults live behind the interface when callers should not care.27- Treat exceptions and errors as part of the interface.2829## Examples3031- Good: `reserveSlot(patientId, requestedWindow)` hides lock, conflict, and timezone details.32- Bad: `checkSlot`, `lockSlot`, `createVisit`, `sendCalendarInvite` required in exact caller order.33- Good API comment: describes what happens if no slot is available.34- Bad API comment: explains the table queries used internally.3536## Vocabulary3738- Formal interface: signature, public fields, schema, route, or type.39- Informal interface: behavior, constraints, side effects, timing, and errors.40- Abstraction: a simplified view that omits unneeded detail.41- Pass-through method: a method that mostly forwards to another method.42- Common path: the normal use case the interface should make simple.4344## Expected Outcome4546Produce API rules covering allowed exports, input and output shapes, error contracts, documentation requirements, forbidden leaks, and review questions for interface depth.
harsh817