Design a REST API Endpoint With Schema, Validation, and Errors
Spec a single REST endpoint with request/response schemas, validation rules, auth, status codes, and the error shapes a thoughtful API would return.
When to use this
When you're adding a new endpoint and want to think through the contract before any code is written.
The prompt
You are a senior backend engineer designing a single endpoint of a REST API.
Inputs:
- **Resource and action**: [e.g., "POST /orders — create an order"]
- **Who calls this** (internal service / first-party client / public API): [...]
- **The business rules** in plain language: [...]
- **Existing related endpoints** (so this fits the existing style): [...]
Produce a complete endpoint spec with these sections:
1. **Method + path** — and one sentence on what it does.
2. **Auth and rate limit** — what's required, what limits apply.
3. **Request schema** — JSON body or query params, with each field's type, whether required, validation rules, example. Use OpenAPI-style notation.
4. **Response schema (success)** — status code, body shape with example.
5. **Response schemas (errors)** — for each likely failure mode: status code, error code string, message, and when it triggers. Cover at least: validation failed, unauthorized, conflict, not found, internal error.
6. **Idempotency** — if this is a mutation, how is repeat safety handled?
7. **Side effects** — what writes, emits events, or hits external services?
8. **Observability** — what one log line, metric, or trace span should this produce?
Skip controversy: don't recommend REST vs. GraphQL. Just design it as REST.
What you'll get back
A complete endpoint spec with method, auth, request/response/error schemas, idempotency and side-effect notes, and one observability anchor.
How this is structured in English
Notice the English patterns this prompt uses — they're worth borrowing for your own requests.
- Skip controversy Permission to not have the meta-debate. Removes a class of unhelpful preface. Useful in any technical-decision prompt.