API Behavior Flow — contracts and decision branches before code

Design-to-delivery integration

For complex API/feature design, consider design-to-delivery: an Excalidraw flow in docs/diagrams/ can guide brainstorming, contract detail in docs/specs/<work-id>/specs.md or linked existing API-FLOW.md, and tasks in docs/task/<work-id>/tasks.md. This recommended sequence helps catch missing error branches and incompatible contracts. Adapt the order, reuse existing documents or omit optional artifacts when a simpler method fits. A diagram is not mandatory merely because this skill is loaded. Preserve prior documents and honor explicitly requested deliverables/timing.

Purpose

Turn "we need an endpoint for X" into an explicit behavior spec — inputs, outputs, every decision branch, error cases, and side effects — before or while implementing it. The spec is the working base the implementation then follows; it prevents the classic failure of discovering missing validation, error paths, and state rules mid-implementation.

Works in two modes:

• Design-first (new API): write the spec, get user confirmation on ambiguous branches, then implement.
• Retro-map (existing API): extract the spec from code, flag gaps and unhandled branches, then fix or document.

When to use

• Designing a new API or a new group of endpoints.
• User asks what an endpoint does in every case, or for input/output flows, decision trees, or API edge cases.
• Before implementing a feature whose backend has non-trivial branching (payments, auth, multi-step state machines, anything with permissions).
• Trigger phrases include: "flow ورودی و خروجی API", "شرط‌هاش چیه", "قبل از پیاده‌سازی بگو هر endpoint چیکار می‌کنه", "map the endpoints first", "what does this API return when…".

Preconditions

• You know the project's stack (NestJS + zod is the house default; method adapts to any framework). Domain rules and auth model: infer from existing code/conventions; ask the user only for genuinely ambiguous business decisions (pricing, permission boundaries).
• For retro-mapping a large API, delegate per-module reading to Explore subagents (same partitioning as behavior-audit); the main agent reads only the module map.
• Context discipline: never paste whole controllers into the spec — extract behavior, not code.

Workflow

1. Scope the surface (main agent — cheap reads only): module list, existing auth guard / interceptor / filter setup, shared DTOs or schemas, error-filter convention. Record the conventions the new endpoints must match (response envelope, error shape, pagination style, ID format).
2. Inventory endpoints. One row per endpoint: method + path · purpose (one line) · auth requirement (public / authenticated / role) · idempotent? · side effects (writes, emails, webhooks, queue jobs). Group by resource. Flag endpoints whose purpose overlaps — that's a design smell to resolve before coding.
3. Per endpoint, extract the contract — this exact shape, as dense bullets:

   • Input: body/query/params fields with types and constraints (zod schema names when they exist); which fields optional; defaults.
   • Decision branches — numbered, exhaustive, in evaluation order: validation → auth/permission → existence/state checks → business rules → concurrency/limits. Each branch names its trigger and its outcome (error code or the path it takes).
   • Outputs: success response shape (per status code — 200 vs 201 vs 204) + every error response with its code and message shape.
   • Side effects & ordering: what gets written/emitted, in what order, and what must be transactional.
   • Open questions: business decisions only the user can make, phrased as either/or.

4. Design the error model once, reuse everywhere. Follow the project's existing error filter; if none exists, define one before endpoint work: error envelope (code, message, field details), HTTP status mapping, which errors are user-facing vs logged. Never invent a per-endpoint error shape.
5. Write API-FLOW.md (repo root or the project's docs convention):
   • Header: scope, date, conventions it assumes.
   • Endpoint inventory table.
   • One section per endpoint in the step-3 shape; mermaid flowchart only for endpoints with ≥3 branches or multi-step state.
   • Open questions section at top — the user answers these before or during implementation; each answered question gets folded into the branch list.
   • Keep it dense bullets; no prose paragraphs.
6. Resolve blocking questions, then implement when requested. Batch genuinely unresolved business decisions; infer safe defaults from existing contracts. Do not require a second approval for already-authorized implementation or implement during a mapping-only request. Implementation follows the spec — each zod schema and guard maps to a listed branch. When the API is implemented per the house API rules (global AGENTS.md → API Standards), the same schemas generate the OpenAPI document — keep API-FLOW.md and the code in sync when branches change later.

Rules

• Branches must be explicit and ordered by the actual framework pipeline. Confirm middleware, guards, validation and rate-limit execution order; the conceptual categories above are not a universal instruction to validate before authentication. Preserve ownership/privacy boundaries and avoid existence leaks.
• No endpoint without an error path. If the spec can't name the error for a failure mode, that's an open question, not a gap to skip.
• Quote code file:line for every claim in retro-map mode; mark unverified items.
• Describe behavior, not implementation. The spec survives refactors; coupled specs rot.
• Auth, validation, and rate-limit decisions must follow the Security Defaults in global AGENTS.md — the spec lists them per endpoint, the rule defines the baseline.
• Diagrams (when asked): excalidraw skill, docs/diagrams/, never raw Excalidraw JSON in chat.
• Add a focused contract case matrix (input/role/state → status/payload/side effects); use behavioral-testing when implementing the cases. Concurrency and rollback need cases when the endpoint actually has those risks.

Common mistakes

• Specifying only the happy path, then "discovering" validation and permission rules during implementation.
• Inventing a new error shape per endpoint instead of using the project's error filter.
• Writing the spec after the code — at that point it documents decisions instead of driving them (still worth doing as a retro-map, but say so).
• Leaving open questions embedded in endpoint sections where the user won't see them.

Verification

• Every endpoint in the inventory has: input schema, ≥1 error branch per failure mode, success shape, side effects listed.
• Every open question is either answered (and folded into branches) or still visibly pending.
• Spot-check retro-mapped claims against source (file:line) — 3–5 highest-risk branches.
• If implemented: zod validation on every input path; OpenAPI doc generated and covering each endpoint (per API Standards rule).