Prompt
Draft API Contract and Data Model
Use this when you need to define endpoints, payloads, and entities before implementation.
How to use it
- Copy the prompt and paste it into ChatGPT, Claude, Gemini or any other AI.
- Replace every {{placeholder}} with your own details, or let the AI ask you for them.
- Use the follow-ups below to go deeper.
Role You are a software architect drafting a review-ready API contract and data model. Optimise for endpoints, payloads, and entities a team can implement and test without follow-up questions.
Context you provide
- {{system_name}}: service or product name
- {{business_goal}}: what the API must enable
- {{consumers}}: client types such as web, mobile, partner, internal
- {{core_entities}}: the things stored, described in plain words
- {{key_operations}}: actions each client must perform
- {{api_style}}: REST, GraphQL, gRPC, or event-driven
- {{auth_model}}: how callers authenticate and are authorised
- {{constraints}}: latency, payload size, versioning, compliance limits
- {{existing_conventions}}: naming, error shape, pagination rules already in use
Instructions
- Ask for any missing inputs above, then confirm the scope in one sentence before drafting.
- List each entity with its fields, types, nullability, and defaults.
- Define the relationships and cardinality between entities.
- Define each endpoint: method, path, purpose, request payload, response payload, and status codes.
- Specify error shapes, pagination, filtering, and idempotency behaviour.
- Note versioning and backward-compatibility rules.
- List open questions and assumptions separately at the end.
Output format Markdown with one table for entities and one for endpoints. One line per field description. Give a request and response example for each main endpoint. Skip marketing language, framework setup, and implementation code. Target 600 to 900 words unless told otherwise.
Guardrails
- Do not invent field names, endpoints, standards numbers, or regulatory rules; mark unknowns as open questions.
- Flag every assumption made where the inputs were silent.
- State when the contract needs security, privacy, or legal review, or must follow a published specification the user has not supplied.
Example System: "Order tracking API" for partner mobile apps; entities: Order, Shipment, Carrier; style: REST with JSON; auth: OAuth 2.0 bearer tokens; constraints: versioned paths, 200 ms p95 target.