---
type: method
slug: api-design
title: "Design a REST API"
category: "Technology & Development"
subcategory: "App & web development"
level: advanced
source: https://deepstoryresearch.com/method/api-design
publisher: Deepstory Research
---

> **How to use this file:** attach it to ChatGPT, Claude, Gemini or Copilot (or paste the prompt section), replace every [PLACEHOLDER] with your details, and add any data or Deepstory evidence files the method needs.

## When to use this method
- Building a backend or public API.

## Prompt

# Design a REST API
Method by Deepstory Research: deepstoryresearch.com/method/api-design

You are an API designer. Follow the method below step by step. Goal: An API spec with resources, endpoints, request/response shapes, errors, auth and versioning.

## My inputs
- Domain: [DOMAIN]  (example: inventory management)
- Consumers: [CONSUMERS]  (example: mobile app and partners)
- Auth: [AUTH]  (example: API keys + OAuth)

Before you start: if any input above is still in [BRACKETS] or missing, ask me for it in one short numbered list and wait. Do not guess. If I attached files (data, briefs, Deepstory evidence files), treat them as the primary source.

## Steps to follow
1. Identify resources and relationships.
2. Define endpoints and methods.
3. Specify JSON shapes and validation.
4. Define error format and status codes.
5. Cover pagination, rate limits, versioning and auth.
6. Output an OpenAPI draft.

## Deliver the output in this structure
- Resource model
- Endpoint table
- Schemas
- Error model
- OpenAPI YAML

## Quality rules
- Consistent naming; idempotency for writes where needed.
- Label every number as FACT (with source and date), ESTIMATE (show the calculation) or ASSUMPTION.
- If a Deepstory evidence file is attached, use its figures as the reference values and cite its source references; tag claims that are not from it as [UNVERIFIED].
- End with: the 3 assumptions that matter most, what would change the answer, and the single best next step.

---
Deepstory methods are process guidance for AI tools. Review AI output before relying on it; legal, tax, medical and investment matters need a qualified professional.