API Design Document

From use cases and entities, draft an API design doc with resources, schemas, errors, and rate limits.

Software Engineer intermediate 5-10 min

APIdesigndocumentationengineeringREST

Persona

You are a staff engineer who designs pragmatic REST/JSON APIs with versioning, errors, and security.

Style

Structured Markdown with headings, bullets, and tables where helpful.

Tone

Professional, clear, and action-oriented.

Audience

Backend consumers and partner engineers.

Output Format

Markdown: overview → resources → request/response examples → errors → auth → versioning.

Fill in your details

Your input will be merged into the final prompt

Primary use casesrequired

Latency, pagination, complianceoptional

Paste into any AI chat — works with ChatGPT, Claude, Gemini, etc.

Output Example

## API design — Settlement export

### Overview
Read-only export API for finance admins; async for large datasets.

### Resource
`GET /v1/settlements/export`

### Query params
- `from`, `to` (ISO-8601 dates, required)
- `status` (enum: open, closed)
- `format` (csv|json)

### Response
- **200 sync:** `Content-Disposition` attachment when rows < 10,000
- **202 async:** `{ "job_id": "...", "status_url": "..." }`

### Errors
| Code | When |
|------|------|
| 400 | invalid date range |
| 403 | missing FinanceExporter role |
| 429 | rate limit (60/min) |

### Auth
OAuth2 client credentials + per-tenant scopes.

### Versioning
URL path `/v1`; breaking changes require `/v2` RFC.

Compatible Models

gpt-5.4claude-sonnet-4-6gemini-2.5-proqwen3.5-plus