wowprompt

REST API endpoint design with error cases and examples

Designs one or more REST endpoints from a feature description, with paths, request and response bodies, status codes and every error case. Use it before writing backend code or when agreeing an API contract with a frontend team.

An endpoint table with methods and paths, request and response JSON examples, an error case table with status codes and a list of validation rules
The output this prompt produced, unedited.

The prompt

Role

You are a backend engineer who designs APIs that are predictable, secure and easy to consume. You design the failure cases as carefully as the success case.

Task

Design the endpoints needed for the feature below, ready to hand to the developers who will build and call them.

Inputs

  • Feature: [e.g. users can save prompts to named collections]
  • Main resources and fields: [e.g. collection: id, name, owner, created date]
  • Who calls it: [web app, mobile app, third-party integrators]
  • Authentication: [session, token, API key]
  • Rules: [e.g. max 50 collections per user, names unique per user]

Output format

  1. Endpoint table:

| Method | Path | Purpose | Auth required | Idempotent |

  1. For each endpoint:
  • Request body or query parameters as a JSON example
  • Success response with status code and JSON example
  • Validation rules for each input field
  1. Error cases table:

| Endpoint | Condition | Status code | Error code | Message |

  1. Pagination and filtering: the approach for any list endpoint.
  2. Security notes: authorisation checks, rate limits and data that must never be returned.

Quality rules

  • Use plural nouns for resources and HTTP methods for actions; no verbs in paths.
  • Use 400 for invalid input, 401 for missing auth, 403 for forbidden, 404 for not found, 409 for conflicts and 422 only if the team already uses it.
  • Every error response uses the same shape, such as an error code and a message.
  • Check ownership on every request that reads or changes a user's resource.
  • Never expose internal IDs, stack traces or other users' data in responses.
  • List endpoints return a page size limit and a way to fetch the next page.
api designrest api endpointsapi error handlinghttp status codesapi specification

How to run this

Copy the prompt and paste it into Gemini, then set the aspect ratio to 3:4. No reference photo is needed for this one.

The prompt is written in Markdown with each part under its own heading, which is what the copy action hands over. Change one section at a time, keeping the rest intact, so you can tell which change did the work.

Related prompts

All productivity