Build an API design prompt that specifies endpoint purpose, resources, authentication, request and response schemas, errors, rate limits, and tests before implementation starts.
Direct answer: A strong API design prompt defines the user goal, endpoint resource, auth model, request fields, response shape, errors, rate limits, versioning, and test cases. It should ask for examples and edge cases, not just a happy-path route.
Interactive engineering prompt builder
Replace the examples with sanitized engineering context. The generated prompt updates locally in your browser; Omellody does not receive these inputs.
Copy-ready base prompt
Act as a pragmatic API architect. Design an API endpoint or small endpoint set for the need below.
User goal: {user_goal}
Resource model: {resource_model}
Authentication and permissions: {auth_model}
Request shape: {request_shape}
Response shape: {response_shape}
Constraints: {constraints}
Return:
1. Recommended endpoint path, method, and one-sentence purpose.
2. Request schema table with field, type, required status, validation, example, and privacy note.
3. Response schema table for success and important partial states.
4. Error model with status code, machine-readable code, human message, retryability, and logging note.
5. Authentication, authorization, idempotency, rate-limit, and pagination decisions where relevant.
6. Three complete request/response examples: happy path, validation error, and permission error.
7. Test plan covering contract, security, edge cases, backwards compatibility, and observability.
8. Open questions that must be resolved before implementation.
Rules: avoid over-engineering; call out breaking changes; protect private data; separate design choices from assumptions.
Prompt formula and variables
Formula: User goal + resource model + auth + request schema + response schema + errors + tests.
Variable
What to enter
Example
{user_goal}
User goal
mobile app needs to create and track subscription cancellation requests
Define resource boundaries, ownership rules, schemas, and examples before writing code.
API refactor
Ask for backwards-compatible migration steps, deprecation notes, and contract tests.
Partner integration
Require stable error codes, retry semantics, idempotency, and documentation examples.
Internal service
Clarify ownership, observability, permissions, timeouts, and failure modes.
Review rubric
Use this rubric before copying the generated prompt into any AI tool. It keeps the output practical instead of vague.
Dimension
What good output should cover
Contract clarity
Are request and response fields typed, validated, named consistently, and documented with examples?
Security
Are authentication, authorization, privacy, logging, and abuse controls explicit?
Reliability
Are idempotency, retry behavior, timeouts, rate limits, pagination, and partial failures addressed?
Testability
Can engineers write contract, permission, validation, and regression tests from the output?
Privacy and safety checklist
Remove passwords, API keys, private certificates, customer records, and unreleased business-sensitive details.
Prefer small sanitized excerpts over whole repositories or production dumps.
Ask the model to label assumptions, confidence, and human-review requirements.
Run tests, type checks, security checks, or staging validation before shipping suggested changes.
Safety note: Do not paste secrets, private keys, proprietary source that your policy forbids, confidential customer data, regulated personal data, or production credentials into public AI tools.
What makes an API prompt better than asking for an endpoint?
The prompt forces context: users, permissions, schemas, errors, examples, and tests. That prevents a shallow route suggestion that fails in production.
Should I ask for OpenAPI output?
Yes if your team uses OpenAPI. First ask for design tradeoffs and examples, then request an OpenAPI fragment after the contract is clear.
How do I handle sensitive data?
Name privacy rules explicitly. Ask the model to mark fields that should not be logged, cached, indexed, or returned to unauthorized users.
Can this design prompt replace an architect?
No. It structures the design conversation. Product, security, data, and platform owners still need to review choices that affect users or contracts.
Source snapshot
This page is an Omellody original utility page refreshed during Red Mode quality recovery on 2026-05-23. It uses first-party prompt structures, local browser generation, developer review checklists, and internal peer links. It does not copy external repositories; public demand signals are used only to understand search intent.
Snapshot fields: title, canonical, direct answer, local builder, variable table, use-case table, review rubric, FAQ, related links, JSON-LD, robots index,follow.