Web Development · Back-end & data
The Best Prompt for REST API Design
The best prompt for API design has the model define the resources and the cross-cutting conventions before it lists a single endpoint, so naming, errors and pagination are decided once and applied everywhere. This prompt returns a resource model, an endpoint table, worked request and response examples, and a list of decisions that need a human. It is written to stop the model from inventing business rules or producing a different error shape on every route.
REST API Design Prompt
Turns a description of your domain and consumers into a consistent REST contract: resources, endpoints, errors, pagination and open decisions.
- Works with
- ChatGPT, Claude, Gemini
- Difficulty
- Intermediate
- Complexity
- Multi-part reply
- Variables
- 6
- Version
- 1.0
Customize this prompt
Fill in what you know. Anything left blank stays as a [bracketed placeholder]. Nothing you type leaves your browser.
6 variables · fields marked * matter most
Act as an API designer who cares most about consistency and about the developers who will call this API. Design a REST API from the brief below. BRIEF Product and domain: [Product and domain] Who will call the API: [API consumers] What it must let them do: [What callers must be able to do] Authentication: [Authentication] Existing conventions or constraints: [Existing conventions or constraints] Deliverable format: [Deliverable format] WORK IN THIS ORDER 1. Resource model. List each resource, its key fields with types, and its relationships. Separate the fields a client may write from those the server sets. Note any resource you considered and rejected. 2. Conventions, decided once. State the rule for each of these and apply it everywhere afterward: URL and field naming, identifier format, timestamps, pagination style, filtering and sorting parameters, the single error body shape (for example RFC 9457 problem details), partial updates, versioning, and how repeated POST requests are made safe. 3. Endpoints. A table with method, path, purpose, success status, and the error statuses a client must handle. Paths are nouns. If an operation does not fit create, read, update or delete, model it as a sub-resource or a clearly named action and explain the choice in one line. 4. Worked examples. For the three operations a new integrator would call first, show a full request and response, plus one realistic error response each. 5. Authorization. Per endpoint or group: who may call it, and what a caller who lacks access receives. 6. Decisions for a human. Trade-offs you resolved by assumption, each with the alternative and what would change your mind. CONSTRAINTS - Do not invent business rules, limits or fields beyond the brief. Where you need one to proceed, label it ASSUMED. - Status codes must mean what HTTP says they mean. No 200 responses carrying an error body. - Every list endpoint is paginated and has a stated default and maximum page size, marked ASSUMED if I gave none. - Never expose internal details such as database column names or sequential ids if the brief suggests they are sensitive. - If two requirements in the brief conflict, say so instead of quietly choosing. OUTPUT Six numbered sections as above, in the deliverable format. No introduction and no closing summary.
Use it when you are
- Drafting the first contract for a new service before any handlers are written
- Preparing an API proposal for review by front-end, mobile or partner teams
- Bringing consistency to a set of endpoints that grew without shared conventions
- Comparing your own design against an independently generated one
Why this prompt works
Conventions are fixed before endpoints exist
Inconsistency is the most common flaw in generated API designs: one list uses page numbers, the next uses cursors, and errors change shape between routes. Making the model write its rules as a separate step, then apply them, gives it a reference to stay consistent with and gives you one place to change a rule.
Capabilities in, endpoints out
The brief asks what callers must be able to do, not which routes you want. That leaves the model room to notice that rescheduling is an update to a booking, or that availability is a read-only resource of its own, instead of transcribing a list of verbs into paths.
Awkward operations get an explicit treatment
Real APIs always contain actions that are not plain create, read, update or delete. Telling the model how to handle them, and to justify each in a line, avoids both extremes: verb-heavy paths everywhere, or a forced resource that nobody would guess.
Error paths are part of the contract
The endpoint table lists the failures a client must handle, and each worked example includes an error response. Integrators spend much of their time on those paths, so a design that specifies them is closer to something a client team can build against.
Assumptions carry a label and a counter-argument
Page-size limits, id formats and versioning are judgment calls the brief rarely covers. The ASSUMED label and the final section, which pairs each choice with its alternative, turn silent guesses into a short agenda that the API's owner can work through in a design review.
How to use it
- Describe the domain in terms of the things it manages and how they relate. Two or three sentences are enough.
- List capabilities from the caller's point of view. Resist writing paths; let the resource model come first.
- Add any rule that is already fixed in your organization, such as casing, id format or pagination style, so the model does not choose a different one.
- Pick Markdown for a design discussion and OpenAPI when you are ready to generate documentation or client code.
- Review section 2 before anything else. A wrong convention there affects every endpoint below it.
- Take section 6 to whoever owns the API and resolve each item before implementation starts.
AI model compatibility
| Model | Status | Notes |
|---|---|---|
| ChatGPT | Expected to work | An OpenAPI document for more than a handful of resources can exceed one reply. Ask for the Markdown deliverable first, settle the design, then request the OpenAPI file one resource group at a time. |
| Claude | Expected to work | If you paste an existing style guide or endpoint list into the conventions field, wrap it in XML-style tags, as Anthropic's guidance suggests, and say whether it is binding or only a reference. |
| Gemini | Expected to work | Keep the numbered order. Asking for conventions before endpoints is what keeps later sections consistent, and Google's prompting guidance favors explicit sequencing. |
“Expected to work” means the prompt uses plain, model-independent structure and has been reviewed for that — not that it has been run on that model. A model is marked Tested only when a test record is published below.
Worked example
Scenario: An illustrative case: a booking product for independent hair salons designing its first API.
Act as an API designer who cares most about consistency and about the developers who will call this API. Design a REST API from the brief below. BRIEF Product and domain: Appointment booking for independent hair salons. Salons have staff and services; staff have working hours; customers book a service with a staff member in a time slot. Who will call the API: Our own React web app and iOS app now; partner booking sites within a year What it must let them do: Browse a salon's services and staff, see open slots for a service on a date, book, reschedule and cancel a booking. Staff can block out time and see their day. Authentication: OAuth 2.0 bearer tokens. Customer and staff roles. Staff only see their own salon. Existing conventions or constraints: camelCase JSON, UUID ids, base path /v1 Deliverable format: Markdown with tables and JSON examples WORK IN THIS ORDER 1. Resource model. List each resource, its key fields with types, and its relationships. Separate the fields a client may write from those the server sets. Note any resource you considered and rejected. 2. Conventions, decided once. State the rule for each of these and apply it everywhere afterward: URL and field naming, identifier format, timestamps, pagination style, filtering and sorting parameters, the single error body shape (for example RFC 9457 problem details), partial updates, versioning, and how repeated POST requests are made safe. 3. Endpoints. A table with method, path, purpose, success status, and the error statuses a client must handle. Paths are nouns. If an operation does not fit create, read, update or delete, model it as a sub-resource or a clearly named action and explain the choice in one line. 4. Worked examples. For the three operations a new integrator would call first, show a full request and response, plus one realistic error response each. 5. Authorization. Per endpoint or group: who may call it, and what a caller who lacks access receives. 6. Decisions for a human. Trade-offs you resolved by assumption, each with the alternative and what would change your mind. CONSTRAINTS - Do not invent business rules, limits or fields beyond the brief. Where you need one to proceed, label it ASSUMED. - Status codes must mean what HTTP says they mean. No 200 responses carrying an error body. - Every list endpoint is paginated and has a stated default and maximum page size, marked ASSUMED if I gave none. - Never expose internal details such as database column names or sequential ids if the brief suggests they are sensitive. - If two requirements in the brief conflict, say so instead of quietly choosing. OUTPUT Six numbered sections as above, in the deliverable format. No introduction and no closing summary.
What a good response should contain
- A resource model that treats availability as a read-only, computed resource and not something clients create
- One stated pagination rule and one error body shape, reused in every later section
- Rescheduling modeled as an update to a booking, and cancellation given a reasoned treatment
- A conflict response for booking a slot that was just taken, shown as a worked error example
- A decisions list that includes assumed page sizes and how duplicate booking requests are handled
This is an illustrative scenario showing how to fill in the prompt and what to look for. It is not a recorded model output. Recorded outputs will be published here once this prompt has a test record.
Testing and editorial review
Status: Untested. Reviewed for structure and clarity by the editorial team. No recorded model test yet.
No test record has been published for this prompt yet. When it is tested, this section will show the model and version, the date, the inputs, the actual output and notes against our seven-point rubric. We do not publish numerical scores.
| Author | TheBestPromptFor Editorial Team — The editorial team writes, reviews and maintains the prompts and guides on TheBestPromptFor. Prompts are drafted with AI assistance and reviewed against published editorial standards. |
|---|---|
| Published | November 15, 2026 |
| Last reviewed | November 15, 2026 |
| Last tested | Not yet tested |
| Version history |
|
Limitations and things to check
- The design reflects only what the brief says. Rules about money, cancellation windows or compliance must come from you.
- Generated OpenAPI can contain structural errors. Run it through a validator or linter before relying on it.
- The model does not know your traffic, so rate limits and page sizes are placeholders to replace with real numbers.
- REST is assumed. If your consumers need subscriptions or highly variable queries, evaluate other styles separately.
Alternative prompts
Web Development
Relational Database Schema Prompt
Designs a relational schema from your entities, rules and real queries: relationships, DDL, constraints and indexes that each trace to a query.
- ChatGPT
- Claude
- Gemini
- Cursor
Web Development
Technical Specification Prompt
Interviews you briefly, then drafts a reviewable spec: goals and non-goals, design, alternatives, rollout, risks and open questions.
- ChatGPT
- Claude
- Gemini
Web Development
Pull Request Code Review Prompt
Reviews a diff the way a careful senior engineer would: intent first, findings ranked by severity, each tied to a line with a suggested fix.
- ChatGPT
- Claude
- Gemini
- Cursor
Related resources
Guide
How to Write a Good AI Prompt
The five parts of a complete prompt (goal, context, task, constraints, output format), with a worked rewrite and a pre-send checklist.
Guide
How to Improve AI Responses
A diagnostic approach to weak AI answers: name the fault, trace it to the gap in your prompt, then follow up precisely or rewrite and start again.
Frequently asked questions
Should I ask for OpenAPI or Markdown first?
Markdown first in most cases. It is quicker to read and argue about, and it fits in one reply. Once the resource model and conventions are agreed, ask for the OpenAPI document, ideally one group of resources at a time, and validate it with a linter.
Can this prompt review an API that already exists?
Partly. Paste the current endpoints into the conventions field and state that they are a reference. The output will show where a fresh design differs, which is useful, but it is not a compatibility analysis and will not plan a migration for existing clients.
What should I do when the model's assumptions are wrong?
Correct them in one message, quoting the ASSUMED items you are changing, and ask for the affected sections only. Because conventions sit in their own section, a change there should be followed by regenerating the endpoint table and the examples.
Sources and references
- Prompt engineering guide — OpenAI
- Prompt engineering overview — Anthropic
Was this prompt useful?
No account needed. Do not include personal information.