What is The API Designer?
The API Designer is a 3-step prompt flow for designing APIs that will be used, maintained, and extended in the real world — not just APIs that work in the happy path during development. It chains CRISP to force complete contract specification before any code is written, Multi-Agent Debate to pressure-test the design from the perspectives of the consumer, security reviewer, and future maintainer simultaneously, and Prompt Chaining to decompose the validated design into a sequenced implementation pipeline where each step's output feeds the next.
The flow targets the most expensive API design failures: incomplete contracts that break consumer integrations, security assumptions that are never made explicit, and implementation gaps that emerge because the design was never sequenced. Specify first, debate second, implement in order third.
When to Use The API Designer
Public-Facing APIs
External APIs where breaking changes have downstream impact on integrations you don't control and can't easily patch.
Cross-Team Contracts
Internal APIs between teams where the consumer team needs a stable contract to build against independently.
Mobile Backend APIs
APIs consumed by mobile apps where breaking changes require app store releases and can't be coordinated quickly.
API Versioning
Designing a v2 API alongside a v1 that must remain stable — where the migration path needs to be planned before implementation.
Auth-Heavy APIs
APIs with complex authorization models — multi-tenant, role-based, or resource-level permissions — where security must be designed in, not added later.
Microservice Interfaces
Service-to-service APIs in a microservices architecture where contract drift causes distributed system failures.
The Flow Algorithm
CRISP — Specify the Full Contract
Use CRISP to produce a complete API specification before any implementation discussion: Clarity (every endpoint, method, path parameter, query parameter, and request body field with types and optionality), Relevance (the business operations this API enables and what each endpoint maps to), Intent (why specific design decisions were made — why POST not PUT, why this resource model), Specificity (every HTTP status code and the exact condition that triggers it, the auth mechanism and token format, the versioning strategy), Precision (error response schemas with machine-readable codes, pagination contract, rate limiting behavior). A spec that a developer who has never heard of this API could implement from alone.
Produces:
A complete API contract document covering all endpoints, request/response models, error schemas, auth, versioning, and design rationale — detailed enough to generate an OpenAPI spec from directly.
Multi-Agent Debate — Pressure-Test the Design
Run the API contract through a structured Multi-Agent Debate with three personas: the API Consumer (a developer integrating this API into their application — what's confusing, what's missing, what will break their use cases), the Security Reviewer (what attack surface does this expose? what are the authorization edge cases? what's missing from the auth design?), and the Future Maintainer (what will be painful to extend in 18 months? where will versioning become a problem? what naming will cause confusion as the API grows?). Each persona produces specific objections. A judge role synthesizes them into a revised contract addressing the highest-severity issues.
Produces:
A stress-tested, revised API contract with documented rationale for design decisions — including the objections that were considered and why they were or weren't incorporated.
Prompt Chaining — Implement in Sequence
Decompose the validated API contract into an explicit implementation chain where each step's output becomes the next step's input: (1) data models and schema definitions, (2) route handler signatures and middleware stack, (3) auth implementation using the models from step 1, (4) request validation using the schemas from step 1, (5) error handling using the error contract, (6) integration tests against the contract. Each chain link is a separate, focused prompt — preventing the "implement everything at once" failure mode where late steps make incompatible assumptions about early ones.
Produces:
A complete, consistent API implementation where every layer was built against the contract and each step was informed by the previous one — with no auth bolted on after the fact and no error handling as an afterthought.
Example Prompt Sequence
Step 1 — CRISP Contract Specification
Produce a complete API contract for a user management API using CRISP: Clarity: Specify every endpoint (method, path, parameters), every request body field (name, type, required/optional), every response field, and the pagination contract for list endpoints. Relevance: The API must support: user registration, login, profile management, and admin user listing. Map each business operation to specific endpoints. Intent: Document the rationale for resource model decisions — why these resources, why these methods, why this URL structure. Specificity: List every HTTP status code used and the exact condition that triggers it. Define the JWT token format, where it goes (header/cookie), and the expiry strategy. Define the versioning strategy (/v1/ prefix or header?). Precision: Define the error response schema with a machine-readable code field. Define the rate limiting behavior (what endpoint, what limit, what happens when exceeded). Define the pagination model (cursor or offset?).
Step 2 — Multi-Agent Debate Design Review
Review the API contract below from three perspectives. Each persona should produce 3-5 specific objections with proposed changes: Persona A — API Consumer: You are a developer integrating this API into a React app. What is confusing, missing, or will break your implementation? Focus on: response field naming, error handling ergonomics, auth token refresh flow, and missing endpoints. Persona B — Security Reviewer: You are a security engineer doing a pre-launch review. What attack surface does this expose? Focus on: authorization edge cases, missing validation, token security, and privilege escalation paths. Persona C — Future Maintainer: You will be extending this API in 18 months without the original designer. What will be painful? Focus on: versioning problems, naming that won't scale, undocumented constraints, and missing extension points. Then: Judge role — synthesize the objections into a prioritized list of required changes and produce a revised contract summary. API Contract from Step 1: [PASTE STEP 1 OUTPUT HERE]
Step 3 — Prompt Chaining Implementation
Implement the user management API using a chained sequence. Each step must use the output of the previous step. Step 3.1 — Data Models: Implement the User model, request/response DTOs, and validation schemas from the contract. Output: TypeScript interfaces and Zod schemas. Step 3.2 — Route Handlers: Using the models from 3.1, implement the route handler signatures and Express router. Output: route file with handler stubs and middleware stack. Step 3.3 — Auth Middleware: Using the User model from 3.1 and the token contract from the spec, implement JWT auth middleware. Output: middleware function. Step 3.4 — Request Validation: Using the Zod schemas from 3.1, implement validation middleware for each endpoint. Output: validation middleware. Step 3.5 — Error Handling: Using the error schema from the spec, implement the global error handler and per-route error cases. Output: error handler and error utility functions. Revised contract from Step 2: [PASTE STEP 2 OUTPUT HERE]
Pros and Cons
Strengths
- Contract-first prevents the most expensive design mistakes
- Multi-persona debate catches blind spots before implementation
- Prompt Chaining ensures implementation consistency across layers
- Produces design rationale documentation as a by-product
- Works for REST, GraphQL, gRPC, or any API style
Trade-offs
- Significantly more upfront work than jumping to implementation
- Debate step can produce conflicting advice that requires judgment
- Prompt Chaining requires managing 5+ sequential prompts
- Over-engineered for internal CRUD APIs with a single consumer
Frequently Asked Questions
What is The API Designer prompt flow?
The API Designer is a 3-step prompt flow that chains CRISP, Multi-Agent Debate, and Prompt Chaining to produce API designs that survive real-world use. It specifies the full contract before writing code, pressure-tests the design through adversarial stakeholder debate, then decomposes the validated design into a sequenced implementation pipeline.
Why specify the full API contract before any implementation?
The most expensive API design mistakes — wrong resource models, missing error codes, broken versioning strategy — are all detectable at the contract level before a line of code is written. CRISP forces complete specification: every endpoint, every request/response model, every error schema, the auth mechanism, and the versioning strategy. Discovering these gaps in a design document costs nothing; discovering them in code review costs a full redesign.
Why use Multi-Agent Debate for API design review?
A self-review of an API design tends to validate your own assumptions. Multi-Agent Debate simulates the three stakeholders who will most forcefully identify design flaws: the API consumer (who has to work with the contract), the security reviewer (who sees the attack surface), and the future maintainer (who will extend it in 18 months). Each persona produces objections the original designer didn't consider, and the judge synthesizes a revised design.
What does Prompt Chaining add that a single implementation prompt doesn't?
A single 'implement this API' prompt produces a monolithic result where later steps make assumptions about earlier ones. Prompt Chaining explicitly sequences the implementation: data models first, then route handlers, then auth middleware, then error handling, then tests — where each step receives the previous step's output as input. This prevents the common gap where the API is designed but auth is bolted on as an afterthought.
Should I use this flow for internal APIs or only public ones?
Both. The contract specification and debate steps are just as valuable for internal APIs — the consumer is a different team instead of an external developer, but the cost of a broken contract is the same. Internal APIs often get less design rigor because 'we can just change it later,' which is exactly when the debate step's future maintainer persona is most valuable.
How detailed should the CRISP specification be in Step 1?
Specific enough that a developer who has never heard of this API could implement it from the spec alone. Every field name, type, and optionality. Every HTTP status code and what triggers it. The auth token format and where it goes. The versioning strategy and how breaking changes are handled. If you can't write it down in Step 1, you haven't designed it yet.