Turn a Feature Description into a REST API Endpoint Spec

Paste a feature description and get a REST API spec with a route table, request and response fields, status codes, exact validation rules, and open questions on auth and pagination.

You getSummary table, one section per endpoint and shared error response shape

Prompt

Prompt
You are a senior backend engineer who writes API specs that frontend and QA teams can build against.

Job: I will paste a feature description right after this prompt. Turn it into a REST API endpoint spec. If the description is too thin to name the resources, ask me up to 3 short numbered questions in one message and wait for my answers.

Rules:
1. Use plural nouns for resources and standard methods (GET, POST, PATCH, DELETE). No verbs in paths.
2. Every route lists its success code plus at least two error codes, each with the exact condition that triggers it.
3. Show request and response bodies as field lists with field name, type, required or optional, and an example value.
4. Every validation rule must be checkable: give exact limits (max length, allowed values, formats), never just "must be valid".
5. Do not decide auth or pagination silently. State the default you used and list it as an open question.

Output format:
1. Summary table: Route | Method | Purpose | Success code | Error codes
2. One section per endpoint: request fields, response fields, validation rules
3. Shared error response shape
4. Open questions: auth, pagination, rate limits, anything else unclear

End with one line naming the biggest assumption you made and what breaks if it is wrong.

Example output

At a glanceBookmark API routes: method and status codesFour endpoints from the example spec
ItemMethodSuccess / Errors
Save a bookmarkPOST /bookmarks201 / 400, 401, 409
List, filter by tagGET /bookmarks200 / 400, 401
Edit title or tagsPATCH /bookmarks/:id200 / 400, 404, 403
Remove a bookmarkDELETE /bookmarks/:id204 / 404, 403

Example for: a team app where members save article bookmarks with up to 5 tags and can filter by tag.

1. Summary

RouteMethodPurposeSuccessErrors
/bookmarksPOSTSave a bookmark201400, 401, 409
/bookmarksGETList bookmarks, filter by tag200400, 401
/bookmarks/:idPATCHEdit title or tags200400, 404, 403
/bookmarks/:idDELETERemove a bookmark204404, 403

2. Endpoints

POST /bookmarks

Request fields

  • url: string, required, "https://example.com/caching-guide"
  • title: string, optional, "Caching Guide"
  • tags: array of string, optional, ["backend", "perf"]

Response fields (201)

  • id: string (UUID), "b7f2c1e0-4a1d-4e5b-9c3a-2f8d6e1a0b44"
  • url, title, tags: as sent
  • created_at: ISO 8601 string, "2024-05-14T09:30:00Z"

Validation

  • url: http or https only, max 2,048 chars
  • title: 1-200 chars; defaults to the URL if missing
  • tags: max 5, each 1-30 chars, lowercase a-z, 0-9 and hyphen
  • 409 if the same user already saved this exact url
GET /bookmarks

Query params: tag (string, optional), limit (1-100, default 20), cursor (string, optional)

Response fields (200)

  • items: array of bookmark objects
  • next_cursor: string or null

Validation: 400 if limit is outside 1-100 or tag fails the tag format.

PATCH /bookmarks/:id

Request fields: title (optional), tags (optional, replaces the full list)
Validation: same limits as POST; 400 if the body has neither field; 403 if the bookmark belongs to another user.

DELETE /bookmarks/:id

No body. Returns 204. 404 if the id does not exist.

3. Shared Error Shape

  • error.code: string, "TAG_LIMIT_EXCEEDED"
  • error.message: string, "A bookmark can have at most 5 tags."
  • error.field: string or null, "tags"

4. Open Questions

  1. Auth: I assumed bearer tokens and per-user bookmarks. Can teammates see each other's bookmarks?
  2. Pagination: I used cursor-based paging. Does the UI need page numbers or a total count?
  3. Rate limits: Is 60 writes per minute per user acceptable?
  4. Duplicates: Should url matching ignore query strings and trailing slashes?

Biggest assumption: bookmarks are private to each user; if they are shared across the team, the 403 rules and the list filter both need a team scope.

Written by AI from this prompt. Your results will vary.

Tips and common edits

Why this works

  • Requiring two error codes with trigger conditions per route forces the edge cases QA would otherwise find late.
  • Exact validation limits replace vague 'must be valid' rules, so the spec can be turned straight into tests.
  • Making auth and pagination explicit open questions stops the model from quietly baking in choices you never made.

Use before writing backend code or a ticket. Have a short feature description ready, even a few sentences from a product doc. Works in ChatGPT, Claude or Gemini; paste the description right after the prompt.

Common edits

  • Ask for an OpenAPI 3.0 YAML version of the spec after the tables.
  • Swap rule 1 for your team's conventions, such as snake_case paths or versioned routes like /v1.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in Coding