Skip to main content
MethodTechnology & DevelopmentApp & web developmentAdvanced

Design a REST API

An API spec with resources, endpoints, request/response shapes, errors, auth and versioning.

This is a practical, copy-paste process for building a backend or public api.. Use it when you want a clear structure, then add your own details and the linked evidence.

Published by Deepstory Research. Reviewed Sep 2026.

How to use this method

  1. 1. Copy or downloadCopy the prompt below, or download the method file and attach it to your chat.
  2. 2. Paste into any AIChatGPT, Claude, Gemini or Copilot. Replace each [PLACEHOLDER] with your details, or let the AI ask you.
  3. 3. Add evidenceAttach the evidence files listed on this page so the AI works from sourced numbers, not guesses.

The prompt

Paste it as-is. The AI will ask for anything still in [BRACKETS].

Download .md
# 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.

What you need to give the AI

InputPlaceholderExample
Domain[DOMAIN]inventory management
Consumers[CONSUMERS]mobile app and partners
Auth[AUTH]API keys + OAuth

Use it when

  • Building a backend or public API.

What you get

  • Resource model
  • Endpoint table
  • Schemas
  • Error model
  • OpenAPI YAML

The procedure, step by step

Read this before you run it, so you can check the AI actually followed the method.

  1. 1

    Identify resources and relationships.

  2. 2

    Define endpoints and methods.

  3. 3

    Specify JSON shapes and validation.

  4. 4

    Define error format and status codes.

  5. 5

    Cover pagination, rate limits, versioning and auth.

  6. 6

    Output an OpenAPI draft.

Quality checks built into the prompt

  • • Consistent naming; idempotency for writes where needed.
  • • Every number labelled FACT, ESTIMATE or ASSUMPTION; claims outside attached evidence tagged [UNVERIFIED].

Evidence for this method

This method runs on your own material: your files, brief or code. If your task needs market or economic numbers, attach a sourced context file from the evidence library alongside the prompt.

Browse evidence

Run next

Methods that chain well after this one.

Technology & DevelopmentWrite automated testsA test plan and test code covering happy paths, edge cases and failures.Technology & DevelopmentThreat-model an applicationA STRIDE threat model with data flows, threats, risk ratings and mitigations.Technology & DevelopmentPlan and build a mobile app with AIA build plan from idea to store release: scope, screens, stack, data model, milestones and AI-assisted build prompts.Technology & DevelopmentBuild a website or landing page with AIA site plan, copy, section structure and the exact code-generation prompts to build and deploy it.

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